From f0bb727a8024b5f3de02a94fd9a92f619e42b18b Mon Sep 17 00:00:00 2001 From: Guillaume ETHEVE Date: Sat, 7 Nov 2026 23:15:29 +0100 Subject: [PATCH] Add opt-in authenticated HTTPS export of R1 health history --- .../app/FaceclawHealthExportSecret.kt | 47 +++++++++ app/bootstrap.android.ts | 2 + app/health/health-export.ts | 72 ++++++++++++++ app/health/health-store.ts | 37 +++++++ app/native/health-export-secret.ts | 13 +++ app/ui/dashboard-settings.ts | 36 ++++++- app/ui/dashboard/settings-menus.ts | 14 +++ docs/validation-health-export.md | 31 ++++++ tests/assistant-settings-visibility.test.cjs | 1 + tests/health-export.test.cjs | 96 +++++++++++++++++++ 10 files changed, 348 insertions(+), 1 deletion(-) create mode 100644 App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawHealthExportSecret.kt create mode 100644 app/health/health-export.ts create mode 100644 app/native/health-export-secret.ts create mode 100644 docs/validation-health-export.md create mode 100644 tests/health-export.test.cjs diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawHealthExportSecret.kt b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawHealthExportSecret.kt new file mode 100644 index 00000000..a5052518 --- /dev/null +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawHealthExportSecret.kt @@ -0,0 +1,47 @@ +package com.faceclaw.app + +import android.content.Context +import android.security.keystore.KeyGenParameterSpec +import android.security.keystore.KeyProperties +import android.util.AtomicFile +import java.io.File +import java.security.KeyStore +import javax.crypto.Cipher +import javax.crypto.KeyGenerator +import javax.crypto.SecretKey +import javax.crypto.spec.GCMParameterSpec + +/** This credential cannot be restored onto a device lacking its Keystore key. */ +object FaceclawHealthExportSecret { + private const val ALIAS = "faceclaw.health.export" + private fun file(context: Context) = AtomicFile(File(context.noBackupFilesDir, "health-export-key")) + private fun key(): SecretKey { + val store = KeyStore.getInstance("AndroidKeyStore").apply { load(null) } + (store.getKey(ALIAS, null) as? SecretKey)?.let { return it } + return KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore").apply { + init(KeyGenParameterSpec.Builder(ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT) + .setBlockModes(KeyProperties.BLOCK_MODE_GCM) + .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE).build()) + }.generateKey() + } + @JvmStatic @Synchronized fun read(context: Context): String { + val held = file(context) + if (!held.baseFile.exists()) return "" + return try { + val bytes = held.readFully() + val cipher = Cipher.getInstance("AES/GCM/NoPadding") + cipher.init(Cipher.DECRYPT_MODE, key(), GCMParameterSpec(128, bytes.copyOfRange(0, 12))) + String(cipher.doFinal(bytes.copyOfRange(12, bytes.size)), Charsets.UTF_8) + } catch (_: Exception) { "" } // Require re-entry after key loss; never log the credential. + } + @JvmStatic @Synchronized fun write(context: Context, value: String) { + val held = file(context) + if (value.isEmpty()) { held.delete(); return } + val cipher = Cipher.getInstance("AES/GCM/NoPadding") + cipher.init(Cipher.ENCRYPT_MODE, key()) + val bytes = cipher.iv + cipher.doFinal(value.toByteArray(Charsets.UTF_8)) + val stream = held.startWrite() + try { stream.write(bytes); held.finishWrite(stream) } + catch (error: Exception) { held.failWrite(stream); throw error } + } +} diff --git a/app/bootstrap.android.ts b/app/bootstrap.android.ts index 82c23dd5..d08a5588 100644 --- a/app/bootstrap.android.ts +++ b/app/bootstrap.android.ts @@ -1,3 +1,4 @@ +import { startHealthExport } from "./health/health-export" import { Application } from '@nativescript/core' import { registerShareIntentHandler } from './native/share-intents' import { installNativeUserAgent } from './util/http' @@ -18,6 +19,7 @@ Application.on(Application.launchEvent, () => { // they are closed would be lost if the process restarted first, so this keeps // them reaching disk regardless. No-op when there is nothing new. startLiveHealthSync() +startHealthExport() // Collect from the ring on a wall-clock cadence (:01 and :31). Without this // nothing drives a pull on a timer at all - only onRingReady() on reconnect - diff --git a/app/health/health-export.ts b/app/health/health-export.ts new file mode 100644 index 00000000..2bf0a54b --- /dev/null +++ b/app/health/health-export.ts @@ -0,0 +1,72 @@ +import { healthStore } from "./health-store-files"; +import { isFixtureData } from "./health-seed"; +import { healthExportEnabledSetting, healthExportUrlSetting, healthExportKeySetting } from "../ui/dashboard-settings"; +import { getStringSetting, setStringSetting } from "../native/settings-store"; +import { fetchTextWithUserAgent } from "../util/http"; + +let running = false; +let started = false; +let status = "Not synchronized"; +export function healthExportStatus(): string { return status; } + +/** One bounded batch, with durable acknowledgement and no overlapping requests. */ +export async function syncHealthExport(): Promise { + if (running) return; + running = true; + try { + if (!healthExportEnabledSetting.get()) { status = "Export disabled"; return; } + if (isFixtureData()) { status = "Sample data is never exported"; return; } + const url = healthExportUrlSetting.get(); + const key = healthExportKeySetting.get(); + if (!url || healthExportUrlSetting.validationError() || !key) { + status = "Configure an HTTPS endpoint and API key"; + return; + } + const generation = getStringSetting("health.export.generation", "0"); + let held: { url?: string; generation?: string; offsets?: Record } = {}; + try { held = JSON.parse(getStringSetting("health.export.cursor", "{}")) ?? {}; } catch { /* First sync. */ } + const offsets = held.url === url && held.generation === generation ? held.offsets ?? {} : {}; + let limit = 200; + let batch = healthStore().exportBatch(offsets, limit); + let body = JSON.stringify({ version: 1, samples: batch.samples, sleep: batch.sleep }); + // Normalized records contain only ASCII keys, numbers and metric names. + // Large sleep histories must fit the server body limit as well as its record limit. + while (body.length > 240_000 && limit > 1) { + limit = Math.max(1, Math.floor(limit / 2)); + batch = healthStore().exportBatch(offsets, limit); + body = JSON.stringify({ version: 1, samples: batch.samples, sleep: batch.sleep }); + } + if (body.length > 240_000) { status = "A health record exceeds the export size limit"; return; } + if (!batch.scanned) { status = "Up to date"; return; } + if (batch.samples.length || batch.sleep.length) { + status = "Sending health data"; + const response = await fetchTextWithUserAgent(url, { + method: "POST", headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" }, + body, + timeoutMs: 30_000, dontFollowRedirects: true, + }); + if (response.status !== 200) { + status = response.status === 401 || response.status === 403 + ? "API key refused; check configuration" : `Server refused batch (HTTP ${response.status}); will retry`; + return; + } + const ack = await response.json<{ accepted?: boolean }>(); + if (ack.accepted !== true) { status = "Invalid server acknowledgement; will retry"; return; } + } + // An edit during the request must not acknowledge data on a different destination. + if (url !== healthExportUrlSetting.get() || generation !== getStringSetting("health.export.generation", "0")) return; + setStringSetting("health.export.cursor", JSON.stringify({ url, generation, offsets: batch.cursor })); + status = "Batch synchronized; remaining history follows automatically"; + } catch { + // Errors may include request headers or data: never log or display them. + status = "Synchronization failed; will retry automatically"; + } finally { running = false; } +} + +/** Android app process only; no extra BLE pulls, wake locks, or background service. */ +export function startHealthExport(): void { + if (started) return; + started = true; + setTimeout(() => { void syncHealthExport(); }, 10_000); + setInterval(() => { void syncHealthExport(); }, 60_000); +} diff --git a/app/health/health-store.ts b/app/health/health-store.ts index beb93e7a..6c07d041 100644 --- a/app/health/health-store.ts +++ b/app/health/health-store.ts @@ -228,6 +228,43 @@ export class HealthStore { // ------------------------------------------------------------------------- // Reading + /** Append-journal cursor, committed by the exporter only after server acknowledgement. + * Revisions appended to an old month are exported too; a time watermark would lose them. + */ + exportBatch(cursor: Record, limit = 200): { + cursor: Record; samples: HealthSample[]; sleep: SleepSession[]; scanned: number; + } { + const next = { ...cursor }; + const samples: HealthSample[] = []; + const sleep: SleepSession[] = []; + let scanned = 0; + for (const name of this.backend.list().filter(candidate => /^samples-\d{4}-\d{2}\.jsonl$/.test(candidate) || candidate === SLEEP_FILE).sort()) { + const text = this.backend.read(name); + if (text === null) throw new Error("Health export could not read history"); + let offset = next[name] ?? 0; + if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length) offset = 0; + while (scanned < limit) { + const end = text.indexOf("\n", offset); + if (end < 0) break; // Never consume a partially written final record. + const line = text.slice(offset, end); + offset = end + 1; + scanned++; + if (name === SLEEP_FILE) { + try { + const session = JSON.parse(line) as SleepSession; + if (session?.timeResolved === true) sleep.push(session); + } catch { /* Ignore incomplete/corrupt journal lines as the local reader does. */ } + } else { + const sample = fromLine(line); + if (sample) samples.push(sample); + } + } + next[name] = offset; + if (scanned >= limit) break; + } + return { cursor: next, samples, sleep, scanned }; + } + /** Every stored sample overlapping [startMs, endMs). Exact - reads shards. */ samplesInRange(startMs: number, endMs: number): HealthSample[] { const out: HealthSample[] = []; diff --git a/app/native/health-export-secret.ts b/app/native/health-export-secret.ts new file mode 100644 index 00000000..baf22dec --- /dev/null +++ b/app/native/health-export-secret.ts @@ -0,0 +1,13 @@ +import { Utils } from "@nativescript/core"; +declare const com: any; + +/** Android Keystore-backed, excluded from backups. Never falls back to plain settings. */ +export function readHealthExportSecret(): string { + if (!global.isAndroid) return ""; + return String(com.faceclaw.app.FaceclawHealthExportSecret.read(Utils.android.getApplicationContext())); +} + +export function writeHealthExportSecret(value: string): void { + if (!global.isAndroid) throw new Error("Health export is available on Android only"); + com.faceclaw.app.FaceclawHealthExportSecret.write(Utils.android.getApplicationContext(), value); +} diff --git a/app/ui/dashboard-settings.ts b/app/ui/dashboard-settings.ts index 6bed4672..18e2877d 100644 --- a/app/ui/dashboard-settings.ts +++ b/app/ui/dashboard-settings.ts @@ -1,3 +1,4 @@ +import { readHealthExportSecret, writeHealthExportSecret } from "../native/health-export-secret"; import { normalizeNightscoutThreshold, type NightscoutThresholds } from "../apps/nightscout/nightscout-alerts"; import { GESTURE_DOUBLE_CLICK, InputEvent } from "./gestures"; import { DEFAULT_BRIGHTNESS_CURVE, normalizeBrightnessCurve, brightnessCurveError } from "../g2/brightness-curve"; @@ -260,6 +261,39 @@ export class ConfigSettingString extends ConfigSett } +/** A changed credential starts a new delivery history without retaining the old secret. */ +class HealthExportKeySetting extends ConfigSettingString { + get(): string { return readHealthExportSecret(); } + set(value: string): string { + const normalized = value.trim(); + if (normalized !== this.get()) { + writeHealthExportSecret(normalized); + setStringSetting("health.export.cursor", ""); + setStringSetting("health.export.generation", String(Number(getStringSetting("health.export.generation", "0")) + 1)); + } + return normalized; + } + getValidValue(): string { return this.get(); } +} + +export const healthExportEnabledSetting = new ConfigSettingBoolean({ + id: "healthExportEnabled", label: "Export health data", storageKey: "health.export.enabled", + defaultValue: false, reportInAnalytics: false, + description: "Send saved R1 health history to your server over HTTPS. Retries while Faceclaw is running; phone storage is retained.", +}); +export const healthExportUrlSetting = new ConfigSettingString({ + id: "healthExportUrl", label: "Endpoint URL", storageKey: "health.export.url", defaultValue: "", + normalize: value => (value ?? "").trim(), + validate: value => !value || /^https:\/\/[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d{1,5})?(?:\/[^\s?#]*)?$/i.test(value) + ? null : "Use an HTTPS URL without credentials, query or fragment", + description: "Full ingestion URL, for example https://health.undefined-dev.fr/v1/health", +}); +export const healthExportKeySetting = new HealthExportKeySetting({ + id: "healthExportKey", label: "API key", storageKey: "health.export.key", defaultValue: "", + inputKind: "password", formatValue: value => value ? "Configured" : "(empty)", + description: "Device-specific write-only key, stored using Android Keystore.", +}); + export const batteryDisplayModeSetting = new ConfigSettingEnum({ id: "batteryDisplayMode", label: "Style", @@ -1680,7 +1714,7 @@ export class EditTextSettingLayer implements Layer { for (let index = 0; index < message.length; index++) { image.drawText(font, 22, messageTop + index * step, message[index]!, 200); } - image.drawText(font, 22, messageTop + (message.length + 2) * step, truncateSetting(this.setting.get(), 52), 220); + image.drawText(font, 22, messageTop + (message.length + 2) * step, truncateSetting(this.setting.inputKind === "password" ? this.setting.displayValue() : this.setting.get(), 52), 220); const error = this.setting.validationError(); if (error) wrapText(font, error, width - 48).forEach((line, index) => image.drawText(font, 22, messageTop + (message.length + 4 + index) * step, line, 180)); diff --git a/app/ui/dashboard/settings-menus.ts b/app/ui/dashboard/settings-menus.ts index f974bb8f..e8b844f4 100644 --- a/app/ui/dashboard/settings-menus.ts +++ b/app/ui/dashboard/settings-menus.ts @@ -1,3 +1,4 @@ +import { healthExportStatus, syncHealthExport } from "../../health/health-export"; import { remoteInputMenuItem } from "./remote-input-menu"; import { knownFolders } from "@nativescript/core"; import { getDefaultSmallFont } from "../../graphics/ui-fonts"; @@ -28,6 +29,9 @@ import type { LayerContext } from "../layers"; import { drawRightValueMenuItem, openModalMenu, submenuItem, type MenuItem } from "../menu"; import { shell } from "../shell/shell"; import { + healthExportEnabledSetting, + healthExportUrlSetting, + healthExportKeySetting, anthropicApiKeySetting, appSwitcherPositionSetting, statusBarPositionSetting, @@ -187,6 +191,16 @@ function settingsSections(): SettingsSection[] { ]; }, }, + ...(!global.isIOS ? [{ + label: "Health export", + get items() { return [ + toggleSettingMenuItem(healthExportEnabledSetting), + textSettingMenuItem(healthExportUrlSetting), + textSettingMenuItem(healthExportKeySetting), + { label: "Sync now", description: healthExportStatus(), onSelect: () => { void syncHealthExport(); } }, + { label: healthExportStatus(), disabled: true, onSelect: () => {} }, + ]; }, + }] : []), { label: "API Keys", items: [ diff --git a/docs/validation-health-export.md b/docs/validation-health-export.md new file mode 100644 index 00000000..e7fda93a --- /dev/null +++ b/docs/validation-health-export.md @@ -0,0 +1,31 @@ +# R1 health export + +Android Settings → Health export uses the existing toggle and text/password +editors. Export defaults off; URL and API key default empty. Only the API key +uses AES-GCM with Android Keystore and an AtomicFile in noBackupFilesDir. Keys +are masked on both glasses and phone. The URL/cursor use shared settings. + +The matching API/manifests live in Infrastructure/FaceclawHealth and SQL dashboards +in GrafanaDashboards/Health. Protocol v1 sends normalized HealthSample/SleepSession +fields with original millisecond timestamps. Batches contain at most 200 records +and 240 KB. HTTPS is mandatory, redirects are refused, and only HTTP 200 with +accepted:true advances the cursor. No health content or keys are logged. + +The exporter reads existing append journals, including revisions to old months, +without extra BLE pulls. Partial trailing lines are retried. Unresolved sleep +sessions and sample fixtures are excluded. Replayed data is upserted server-side. +A new URL/key resets delivery history safely. One batch runs per minute while +the Android process is alive; this adds no background service or wake lock and +does not promise synchronization while the app is stopped. Disable preserves +local history and existing server data. Watch/iOS export is outside this change. + +Software validation: exporter tests for replay, revisions, failed/malformed +acknowledgements, redirects, destination/credential edits, fixtures, partial +records and overlapping requests; full JS suite, TypeScript and Android release +compilation. API tests additionally cover PostgreSQL rollback and deduplication. + +Hardware/end-to-end validation remains pending: enable ring health sync, configure +the deployed URL/key, then compare measured timestamps/values and sleep durations +with Grafana. Test offline/reconnect, app restart, disable/re-enable and rotated +keys. Check key masking, log redaction and preservation of other preferences. +No firmware modification is needed. diff --git a/tests/assistant-settings-visibility.test.cjs b/tests/assistant-settings-visibility.test.cjs index 43e96713..a349a113 100644 --- a/tests/assistant-settings-visibility.test.cjs +++ b/tests/assistant-settings-visibility.test.cjs @@ -40,6 +40,7 @@ function settingsEnv(initialUrl = '', initialModel = 'openai-compatible') { }, }); const load = loader({ global: { isIOS: false, isAndroid: true } }, { + '../../health/health-export': { healthExportStatus: () => 'Export disabled', syncHealthExport() {} }, './remote-input-menu': { remoteInputMenuItem: () => ({ label: 'Remote input' }) }, '@nativescript/core': { knownFolders: {} }, '../../graphics/ui-fonts': { getDefaultSmallFont: () => ({}) }, diff --git a/tests/health-export.test.cjs b/tests/health-export.test.cjs new file mode 100644 index 00000000..ed948469 --- /dev/null +++ b/tests/health-export.test.cjs @@ -0,0 +1,96 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { loader } = require('./helpers/load-typescript.cjs'); + +function setup() { + const files = new Map(); + const backend = { list: () => [...files.keys()], read: name => files.get(name) ?? null, + exists: name => files.has(name), append: (name, text) => files.set(name, (files.get(name) ?? '') + text), + write: (name, text) => files.set(name, text) }; + const { HealthStore } = loader()('app/health/health-store.ts'); + const store = new HealthStore(backend); + const settings = new Map(); + let url = 'https://health.example/v1/health', key = 'private-test-key', enabled = true, fixture = false; + let response = { status: 200, json: async () => ({ accepted: true }) }; + const requests = []; + const exporter = loader({ setTimeout, setInterval }, { + './health-store-files': { healthStore: () => store }, + './health-seed': { isFixtureData: () => fixture }, + '../ui/dashboard-settings': { + healthExportEnabledSetting: { get: () => enabled }, + healthExportUrlSetting: { get: () => url, validationError: () => url.startsWith('https://') ? null : 'HTTPS required' }, + healthExportKeySetting: { get: () => key }, + }, + '../native/settings-store': { getStringSetting: (k, d) => settings.get(k) ?? d, setStringSetting: (k, v) => settings.set(k, v) }, + '../util/http': { fetchTextWithUserAgent: async (url, options) => { requests.push({ url, options }); return typeof response === 'function' ? response() : response; } }, + })('app/health/health-export.ts'); + return { store, files, settings, exporter, requests, + configure: options => { if ('url' in options) url=options.url; if ('enabled' in options) enabled=options.enabled; if ('fixture' in options) fixture=options.fixture; if ('response' in options) response=options.response; } }; +} +const sample = { metric:'heartRate',startMs:1700000000000,spanMs:3600000,min:60,max:90,avg:75,total:0 }; + +test('exports original measurements, acknowledges durably and catches revisions to old buckets', async () => { + const h=setup();h.store.ingestSamples([sample]); + await h.exporter.syncHealthExport(); + assert.equal(h.requests.length,1); + assert.deepEqual(JSON.parse(h.requests[0].options.body),{version:1,samples:[sample],sleep:[]}); + assert.equal(h.requests[0].options.dontFollowRedirects,true); + assert.ok(!h.settings.get('health.export.cursor').includes('private-test-key')); + await h.exporter.syncHealthExport();assert.equal(h.requests.length,1); + h.store.ingestSamples([{...sample,avg:80}]);await h.exporter.syncHealthExport(); + assert.equal(JSON.parse(h.requests[1].options.body).samples[0].avg,80); + h.configure({url:'https://another.example/v1/health'});await h.exporter.syncHealthExport(); + assert.equal(h.requests.length,3); +}); + +test('failed or malformed acknowledgements retain cursor for replay; no secret in status', async () => { + for (const response of [{status:401},{status:503},{status:302},{status:200,json:async()=>({})},()=>Promise.reject(new Error('private-test-key'))]) { + const h=setup();h.store.ingestSamples([sample]);h.configure({response});await h.exporter.syncHealthExport(); + assert.equal(h.settings.has('health.export.cursor'),false); + assert.ok(!h.exporter.healthExportStatus().includes('private-test-key')); + h.configure({response:{status:200,json:async()=>({accepted:true})}}); + await h.exporter.syncHealthExport();assert.equal(h.requests.length,2); + } +}); + +test('disabled export, fixtures, missing key configuration and HTTP never upload', async () => { + for (const config of [{enabled:false},{fixture:true},{url:'http://health.example/v1/health'},{url:''}]) { + const h=setup();h.store.ingestSamples([sample]);h.configure(config); + await h.exporter.syncHealthExport();assert.equal(h.requests.length,0); + } +}); + +test('bounded batches preserve partial lines, unresolved sleep and late appends', () => { + const h=setup();h.store.ingestSamples([sample]); + const name=[...h.files.keys()].find(n=>n.startsWith('samples-')); + const first=h.store.exportBatch({},1);assert.equal(first.scanned,1); + const second=h.store.exportBatch(first.cursor,200);assert.equal(second.samples.length,1); + h.files.set(name,h.files.get(name)+'{"m":'); + const partial=h.store.exportBatch(second.cursor);assert.equal(partial.scanned,0); + h.files.set(name,h.files.get(name)+'"hrv","t":1700000000000,"s":3600000,"n":1,"x":3,"a":2,"u":0}\n'); + assert.equal(h.store.exportBatch(partial.cursor).samples[0].metric,'hrv'); + h.files.set('sleep.jsonl',JSON.stringify({timeResolved:false,startMs:12})+'\n'); + assert.equal(h.store.exportBatch({}).sleep.length,0); +}); + +test('concurrent ticks and changed credentials cannot incorrectly acknowledge a batch', async () => { + const h=setup();h.store.ingestSamples([sample]);let release; + h.configure({response:()=>new Promise(resolve=>{release=resolve;})}); + const first=h.exporter.syncHealthExport();await h.exporter.syncHealthExport(); + assert.equal(h.requests.length,1); + h.settings.set('health.export.generation','1');release({status:200,json:async()=>({accepted:true})}); + await first;assert.equal(h.settings.has('health.export.cursor'),false); +}); + +test('large sleep histories split into bounded bodies without losing sessions', async () => { + const h=setup(); + const sessions=Array.from({length:6},(_,i)=>({timeResolved:true,startMs:1700000000000+i*86400000, + endMs:1700028800000+i*86400000,dayStartMs:1699920000000+i*86400000, + totalSec:28000,wakeSec:800,remSec:4000,lightSec:18000,deepSec:6000, + segments:Array.from({length:2000},()=>({stageId:2,halfMinutes:1}))})); + h.files.set('sleep.jsonl',sessions.map(s=>JSON.stringify(s)+'\n').join('')); + for(let i=0;i<10;i++) await h.exporter.syncHealthExport(); + assert.ok(h.requests.length>1); + assert.ok(h.requests.every(r=>r.options.body.length<=240000)); + assert.equal(h.requests.reduce((n,r)=>n+JSON.parse(r.options.body).sleep.length,0),sessions.length); +});