health-export-mcp 1.4.4 → 1.5.0

package/README.md

@@ -200,11 +200,57 @@ node server.mjs --help
 - **Read-only.** The server only reads your exported data, it never touches HealthKit and never writes back.
 - **Local-first.** It runs on your machine over stdio. There is **no developer server** in the path.
 - **Optional pairing.** Set `PAIRING_SECRET` to the code the iOS app shows (Settings → Agent pairing) to gate access.
+- **Encrypted exports (optional).** If you switch on Export encryption in the iOS app, set `HEALTH_EXPORT_PASSPHRASE` (or `HEALTH_EXPORT_PASSPHRASE_FILE`) to the same passphrase and the server decrypts on your machine. See [Encrypted exports](#encrypted-exports).
 - **Auditable.** Zero dependencies and a few hundred lines of readable JavaScript, read every line.
 - **Signed releases.** Hosted artifacts are minisign-signed and checksummed, see [Verifying releases](#verifying-releases).
 
 ---
 
+## Encrypted exports
+
+The iOS app can encrypt what it exports with a passphrase you choose (Settings > Export encryption,
+switched on per destination: iCloud Drive, a folder, your server, the local network). Give the server
+the same passphrase and every file is decrypted transparently, in memory, on this machine:
+
+```bash
+HEALTH_EXPORT_PASSPHRASE='your passphrase' HEALTH_DATA_DIR=... node server.mjs
+# or keep it out of your shell history and process list:
+HEALTH_EXPORT_PASSPHRASE_FILE=~/.config/metricbridge/passphrase HEALTH_DATA_DIR=... node server.mjs
+```
+
+If both are set, `HEALTH_EXPORT_PASSPHRASE` wins; one trailing newline in the file is ignored and an
+empty value counts as unset. The `.mcpb` bundle has an optional **Export passphrase** field. Plaintext
+exports keep working either way. A missing or wrong passphrase, or a file that fails its integrity
+check, is reported as such (`get_mcp_status` says `encrypted: true` plus the reason, `--doctor` prints
+an `encryption:` line), never as "no data". The passphrase is never logged or echoed.
+
+The LAN receiver (`HEALTH_LISTEN=1`) decrypts encrypted pushes with the same variable and answers
+`422` with a machine `reason` (`passphrase_missing`, `passphrase_mismatch`, `tampered`, `malformed`,
+`unsupported_version`, `passphrase_file_unreadable`, `encryption_required`). The pairing token rides
+in a plain `http` header on that leg, so set `HEALTH_REQUIRE_ENCRYPTED=1` to refuse plaintext pushes
+once the app encrypts that leg. To decrypt one body yourself (a webhook you run, a script):
+
+```bash
+HEALTH_EXPORT_PASSPHRASE='...' node envelope.mjs open body.json     # prints the decrypted JSON
+```
+
+**Format** (`metricbridge.enc` v1, `envelope.mjs`, `node:crypto` only): a JSON object
+`{format, v, alg: "A256GCM", kdf: "PBKDF2-HMAC-SHA256", iter, salt, kcv, nonce, ct}`.
+`master = PBKDF2-HMAC-SHA256(NFC(passphrase), salt[16], iter)` (600,000 iterations, the OWASP
+figure); an AES-256-GCM key and an 8-byte key-check value come off it with HKDF-SHA256; each message
+gets a random 12-byte nonce; every header field is bound in as AAD as the string
+`metricbridge.enc|v=1|alg=A256GCM|kdf=PBKDF2-HMAC-SHA256|iter=<n>|salt=<b64>|kcv=<b64>|nonce=<b64>`.
+Base64 is canonical with padding. `test/fixtures/` holds envelopes made by the iOS app's Swift encoder
+and by this module; `envelope.test.mjs` proves both open and regenerate byte for byte.
+
+**What it protects:** the export at rest in the destination (iCloud Drive, a synced folder, a
+webhook host's storage) and the LAN push on the wire, plus integrity of every sealed file. **What it
+does not:** an unlocked phone, this computer (it holds the passphrase), metadata (sizes, timing),
+rollback or replay of a whole sealed file, files you share by hand from the app, or a weak passphrase
+(anyone with the files can guess offline; the app requires at least 8 characters).
+
+---
+
 ## Verifying releases
 
 The server artifacts hosted at `healthexport.dev/mcp/` (used by the [setup skill](https://healthexport.dev/SKILL.md)) are **minisign-signed**, and every download is **SHA-256 checksummed**. The signing public key is published **in this repo** (`minisign.pub`) and in `SKILL.md`, **pin it from here, not only from the website**, so a compromise of the website alone cannot swap both an artifact and its key.

package/envelope.mjs

@@ -0,0 +1,239 @@
+// envelope.mjs: reads (and, for tests and tooling, writes) the MetricBridge encrypted export
+// envelope, format "metricbridge.enc" version 1. Zero dependencies: node:crypto only.
+//
+// The iOS app can seal what it exports (iCloud Drive / folder files, webhook and local-network
+// bodies) under a passphrase the user chose. This module is the matching decrypt step, so the MCP
+// server and the LAN receiver read encrypted exports transparently once they know the passphrase.
+//
+// Envelope (UTF-8 JSON, keys sorted):
+//   { "alg":"A256GCM", "ct":"<b64 ciphertext||16-byte tag>", "format":"metricbridge.enc",
+//     "iter":600000, "kcv":"<b64 8 bytes>", "kdf":"PBKDF2-HMAC-SHA256",
+//     "nonce":"<b64 12 bytes>", "salt":"<b64 16 bytes>", "v":1 }
+//
+//   master = PBKDF2-HMAC-SHA256(NFC(passphrase), salt, iter, 32)
+//   encKey = HKDF-SHA256(master, salt = empty, info = "metricbridge.enc/v1/aes-256-gcm", 32)
+//   kcv    = HKDF-SHA256(master, salt = empty, info = "metricbridge.enc/v1/key-check", 8)
+//   AAD    = "metricbridge.enc|v=1|alg=A256GCM|kdf=PBKDF2-HMAC-SHA256|iter=<n>|salt=<b64>|kcv=<b64>|nonce=<b64>"
+//            (base64 re-encoded from the decoded bytes, canonical with padding)
+//
+// Full specification and threat model: docs/ENCRYPTED-EXPORTS.md in the app repo, and the
+// "Encrypted exports" section of README.md.
+//
+// Passphrase source, in order: HEALTH_EXPORT_PASSPHRASE, then the file named by
+// HEALTH_EXPORT_PASSPHRASE_FILE (one trailing newline is stripped). The passphrase is never logged,
+// never echoed in an error and never written anywhere.
+//
+// CLI (for webhook receivers and scripts that want the plaintext of one envelope):
+//   HEALTH_EXPORT_PASSPHRASE=... node envelope.mjs open <file|->      # prints the decrypted JSON
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const FORMAT = 'metricbridge.enc';
+export const VERSION = 1;
+export const ALG = 'A256GCM';
+export const KDF = 'PBKDF2-HMAC-SHA256';
+export const DEFAULT_ITERATIONS = 600_000;   // OWASP Password Storage Cheat Sheet, PBKDF2-HMAC-SHA256
+export const MIN_ITERATIONS = 100_000;       // a forged header cannot steer us into a cheap derivation
+export const MAX_ITERATIONS = 10_000_000;    // ...or pin the CPU for minutes
+const SALT_LEN = 16, NONCE_LEN = 12, KCV_LEN = 8, TAG_LEN = 16, KEY_LEN = 32;
+const ENC_INFO = Buffer.from('metricbridge.enc/v1/aes-256-gcm', 'utf8');
+const KCV_INFO = Buffer.from('metricbridge.enc/v1/key-check', 'utf8');
+
+/** Machine-readable failure. `code` is stable; `message` never contains the passphrase. */
+export class EnvelopeError extends Error {
+  constructor(code, message) { super(message); this.name = 'EnvelopeError'; this.code = code; }
+}
+
+export const isEnvelope = (obj) =>
+  !!obj && typeof obj === 'object' && !Array.isArray(obj) && obj.format === FORMAT;
+
+/** The configured passphrase, or null. Read on every call so tests (and a restarted config) see
+ *  the current environment; it is cheap. Empty means unset: the .mcpb manifest maps an empty
+ *  optional field to an empty string. */
+export function configuredPassphrase(env = process.env) {
+  const direct = env.HEALTH_EXPORT_PASSPHRASE;
+  if (typeof direct === 'string' && direct.length > 0) return direct;
+  const file = env.HEALTH_EXPORT_PASSPHRASE_FILE;
+  if (typeof file === 'string' && file.length > 0) {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); }
+    catch (e) {
+      throw new EnvelopeError('passphrase_file_unreadable',
+        `HEALTH_EXPORT_PASSPHRASE_FILE points at a file that could not be read (${e.code || 'error'}).`);
+    }
+    const p = text.replace(/\r?\n$/, '');
+    return p.length > 0 ? p : null;
+  }
+  return null;
+}
+
+// PBKDF2 at 600,000 rounds is ~0.3 s; every file the app writes shares one salt, so derive once per
+// (passphrase, salt, iter). Keyed by an HMAC of the passphrase under a per-process random key, so the
+// map holds neither a second copy of the passphrase nor a fast unsalted hash of it.
+// Bounded (LRU): the app uses one salt per passphrase, so a handful of entries is plenty, and an
+// unbounded map would let a stream of fresh-salt envelopes grow memory without limit.
+const keyCache = new Map();
+const KEY_CACHE_MAX = 16;
+const CACHE_ID_KEY = crypto.randomBytes(32);
+
+function b64(buf) { return Buffer.from(buf).toString('base64'); }
+
+function decodeField(env, name, len) {
+  const s = env[name];
+  // Canonical padded base64 only: Buffer.from is lenient (drops padding, ignores stray characters)
+  // and the Swift reader is not, so both apply the same rule and accept exactly the same envelopes.
+  if (typeof s !== 'string' || s.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(s)) {
+    throw new EnvelopeError('malformed', `encrypted export is malformed (field "${name}")`);
+  }
+  const buf = Buffer.from(s, 'base64');
+  if (buf.toString('base64') !== s) {
+    throw new EnvelopeError('malformed', `encrypted export is malformed (field "${name}")`);
+  }
+  if (len !== undefined && buf.length !== len) {
+    throw new EnvelopeError('malformed', `encrypted export is malformed (field "${name}" length)`);
+  }
+  return buf;
+}
+
+function exactInt(v) { return Number.isInteger(v) ? v : null; }
+
+/** Parse and validate the header of an envelope object. */
+export function parseHeader(env) {
+  if (!isEnvelope(env)) throw new EnvelopeError('malformed', 'not an encrypted export');
+  const v = exactInt(env.v);
+  if (v === null) throw new EnvelopeError('malformed', 'encrypted export is malformed (field "v")');
+  if (v !== VERSION) {
+    throw new EnvelopeError('unsupported_version',
+      `This export was encrypted with envelope version ${v}, but this server only reads version ${VERSION}. ` +
+      'Update the MetricBridge MCP server.');
+  }
+  if (env.alg !== ALG) throw new EnvelopeError('malformed', 'encrypted export is malformed (field "alg")');
+  if (env.kdf !== KDF) throw new EnvelopeError('malformed', 'encrypted export is malformed (field "kdf")');
+  const iter = exactInt(env.iter);
+  if (iter === null || iter < MIN_ITERATIONS || iter > MAX_ITERATIONS) {
+    throw new EnvelopeError('malformed', 'encrypted export is malformed (field "iter")');
+  }
+  const salt = decodeField(env, 'salt', SALT_LEN);
+  const kcv = decodeField(env, 'kcv', KCV_LEN);
+  const nonce = decodeField(env, 'nonce', NONCE_LEN);
+  const sealed = decodeField(env, 'ct');
+  if (sealed.length < TAG_LEN) throw new EnvelopeError('malformed', 'encrypted export is malformed (field "ct")');
+  return { v, iter, salt, kcv, nonce, sealed };
+}
+
+export function associatedData({ v, iter, salt, kcv, nonce }) {
+  return Buffer.from(
+    `${FORMAT}|v=${v}|alg=${ALG}|kdf=${KDF}|iter=${iter}|salt=${b64(salt)}|kcv=${b64(kcv)}|nonce=${b64(nonce)}`,
+    'utf8');
+}
+
+/** Derive { encKey, kcv } for a passphrase + salt + iteration count (memoized). */
+export function deriveKeys(passphrase, salt, iter) {
+  if (typeof passphrase !== 'string' || passphrase.length === 0) {
+    throw new EnvelopeError('passphrase_missing', 'no passphrase');
+  }
+  const pw = Buffer.from(passphrase.normalize('NFC'), 'utf8');
+  const id = crypto.createHmac('sha256', CACHE_ID_KEY).update(pw).digest('hex') + '|' + b64(salt) + '|' + iter;
+  const hit = keyCache.get(id);
+  if (hit) { keyCache.delete(id); keyCache.set(id, hit); return hit; }
+  const master = crypto.pbkdf2Sync(pw, salt, iter, KEY_LEN, 'sha256');
+  const keys = {
+    encKey: Buffer.from(crypto.hkdfSync('sha256', master, Buffer.alloc(0), ENC_INFO, KEY_LEN)),
+    kcv: Buffer.from(crypto.hkdfSync('sha256', master, Buffer.alloc(0), KCV_INFO, KCV_LEN)),
+  };
+  master.fill(0);
+  pw.fill(0);
+  keyCache.set(id, keys);
+  while (keyCache.size > KEY_CACHE_MAX) keyCache.delete(keyCache.keys().next().value);
+  return keys;
+}
+
+/** Decrypt an envelope object to a Buffer of plaintext. Throws EnvelopeError with code
+ *  'passphrase_missing' | 'passphrase_mismatch' | 'tampered' | 'malformed' | 'unsupported_version'. */
+export function openEnvelope(env, passphrase = configuredPassphrase()) {
+  const h = parseHeader(env);
+  if (!passphrase) {
+    throw new EnvelopeError('passphrase_missing',
+      'This health export is encrypted. Set HEALTH_EXPORT_PASSPHRASE (or HEALTH_EXPORT_PASSPHRASE_FILE) ' +
+      'to the passphrase you chose in the MetricBridge app (Settings > Export encryption), then restart the server.');
+  }
+  const { encKey, kcv } = deriveKeys(passphrase, h.salt, h.iter);
+  if (!crypto.timingSafeEqual(kcv, h.kcv)) {
+    throw new EnvelopeError('passphrase_mismatch',
+      'This health export is encrypted with a different passphrase than HEALTH_EXPORT_PASSPHRASE. ' +
+      'Use the passphrase set in the MetricBridge app (Settings > Export encryption).');
+  }
+  const ct = h.sealed.subarray(0, h.sealed.length - TAG_LEN);
+  const tag = h.sealed.subarray(h.sealed.length - TAG_LEN);
+  try {
+    const d = crypto.createDecipheriv('aes-256-gcm', encKey, h.nonce, { authTagLength: TAG_LEN });
+    d.setAAD(associatedData(h));
+    d.setAuthTag(tag);
+    return Buffer.concat([d.update(ct), d.final()]);
+  } catch {
+    throw new EnvelopeError('tampered',
+      'An encrypted health export failed its integrity check: the file is damaged or was modified. ' +
+      'Run an export from the MetricBridge app to rewrite it.');
+  }
+}
+
+/** Decrypt and JSON.parse. */
+export function openEnvelopeJSON(env, passphrase) {
+  return JSON.parse(openEnvelope(env, passphrase).toString('utf8'));
+}
+
+/** If `obj` is an envelope, return its decrypted JSON; otherwise return it unchanged. */
+export function maybeOpen(obj, passphrase) {
+  return isEnvelope(obj) ? openEnvelopeJSON(obj, passphrase === undefined ? configuredPassphrase() : passphrase) : obj;
+}
+
+/** Seal plaintext (Buffer or string) into an envelope object. Used by tests, by the cross-language
+ *  fixture and by the receiver when it rewrites a cache that was already sealed. `nonce` and `salt`
+ *  are injectable for deterministic fixtures ONLY: production use must leave both to the CSPRNG. */
+export function sealEnvelope(plaintext, passphrase, { salt, iter = DEFAULT_ITERATIONS, nonce } = {}) {
+  const s = salt ? Buffer.from(salt) : crypto.randomBytes(SALT_LEN);
+  const n = nonce ? Buffer.from(nonce) : crypto.randomBytes(NONCE_LEN);
+  if (s.length !== SALT_LEN || n.length !== NONCE_LEN) throw new EnvelopeError('malformed', 'bad salt or nonce length');
+  const { encKey, kcv } = deriveKeys(passphrase, s, iter);
+  const header = { v: VERSION, iter, salt: s, kcv, nonce: n };
+  const c = crypto.createCipheriv('aes-256-gcm', encKey, n, { authTagLength: TAG_LEN });
+  c.setAAD(associatedData(header));
+  const ct = Buffer.concat([c.update(Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(String(plaintext), 'utf8')), c.final()]);
+  // Same key order the app writes (sorted), so a fixture regenerates byte-for-byte.
+  return {
+    alg: ALG,
+    ct: b64(Buffer.concat([ct, c.getAuthTag()])),
+    format: FORMAT,
+    iter,
+    kcv: b64(kcv),
+    kdf: KDF,
+    nonce: b64(n),
+    salt: b64(s),
+    v: VERSION,
+  };
+}
+
+// ---- CLI ----
+const isEntryPoint = (() => {
+  if (!process.argv[1]) return false;
+  try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+})();
+if (isEntryPoint) {
+  const [cmd, file] = process.argv.slice(2);
+  if (cmd !== 'open' || !file) {
+    process.stderr.write('usage: HEALTH_EXPORT_PASSPHRASE=... node envelope.mjs open <file|->\n');
+    process.exit(2);
+  }
+  try {
+    const text = fs.readFileSync(file === '-' ? 0 : file, 'utf8');
+    const obj = JSON.parse(text);
+    if (!isEnvelope(obj)) { process.stdout.write(text); process.exit(0); }
+    process.stdout.write(openEnvelope(obj).toString('utf8'));
+  } catch (e) {
+    process.stderr.write(`envelope: ${e instanceof EnvelopeError ? e.message : 'could not read input (' + (e.code || e.name) + ')'}\n`);
+    process.exit(1);
+  }
+}

package/healthstore.mjs

@@ -26,6 +26,9 @@ import os from 'node:os';
 // functions, never at module-evaluation time.
 import { DEMO, demoData } from './demo.mjs';
 import * as ev from './events.mjs';
+// Encrypted exports (opt-in in the iOS app): every data file may be a "metricbridge.enc" envelope.
+// readJSON opens it with HEALTH_EXPORT_PASSPHRASE, so every reader below is transparent to it.
+import { isEnvelope, openEnvelope, configuredPassphrase, EnvelopeError } from './envelope.mjs';
 
 // Expand a leading ~ (Node, unlike the shell, does not) so manual configs resolve correctly.
 const RAW_DIR = process.env.HEALTH_DATA_DIR || '.';
@@ -48,7 +51,9 @@ const MAX_BYTES = Number(process.env.HEALTH_MAX_CACHE_BYTES || 512 * 1024 * 1024
 
 class CacheTooLarge extends Error {}
 
-function readJSON(file, fallback) {
+// `info.encrypted` is set when the file was an envelope, so callers that memoize the parse (and
+// `encryptionStatus`) know without parsing a tens-of-MB file a second time.
+function readJSON(file, fallback, info = {}) {
   let st;
   try {
     st = fs.statSync(file);
@@ -59,9 +64,54 @@ function readJSON(file, fallback) {
       `health cache is ${(st.size / 1048576).toFixed(1)} MB, above the ${(MAX_BYTES / 1048576).toFixed(0)} MB read limit. ` +
       `Raise HEALTH_MAX_CACHE_BYTES if this is expected.`);
   }
+  let parsed;
   try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch { return fallback; }              // corrupt -> fall back rather than crash the server
+  // An encrypted export is NOT corrupt and must never read as "no data": no passphrase, the wrong
+  // passphrase and a failed integrity check each THROW an EnvelopeError whose message says exactly
+  // what to do. The passphrase itself never appears in any message.
+  if (isEnvelope(parsed)) {
+    info.encrypted = true;
+    const plain = openEnvelope(parsed);
+    // An envelope that authenticates but holds bytes that are not JSON (a truncated write the app
+    // sealed as raw bytes) is a damaged export, not a crash: reported as an EnvelopeError so
+    // get_mcp_status explains it instead of rethrowing a bare SyntaxError.
+    try { return JSON.parse(plain.toString('utf8')); }
+    catch {
+      throw new EnvelopeError('corrupt',
+        'An encrypted health export opened with your passphrase but its contents are damaged. ' +
+        'Run an export from the MetricBridge app to rewrite it.');
+    }
+  }
+  return parsed;
+}
+
+/** What the data directory's encryption looks like, for get_mcp_status and `doctor`. Reads only
+ *  the envelope header (no decryption is attempted beyond what loading the data already does). */
+export function encryptionStatus() {
+  if (DEMO) return { encrypted: false };
+  const file = path.join(DATA_DIR, '.health-cache.json');
+  // The cache was almost always just parsed (status() loads it first): reuse that answer rather
+  // than parsing a file that reaches tens of MB again. Fall back to a header read when it was not.
+  let encrypted;
+  const hit = _memo.get(file);
+  if (hit) {
+    try {
+      const st = fs.statSync(file);
+      if (hit.stamp === `${st.mtimeMs}:${st.size}`) encrypted = hit.encrypted;
+    } catch { return { encrypted: false }; }
+  }
+  if (encrypted === undefined) {
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { return { encrypted: false }; }
+    encrypted = isEnvelope(raw);
+  }
+  if (!encrypted) return { encrypted: false };
+  let configured = false;
+  try { configured = !!configuredPassphrase(); } catch { configured = false; }
+  return { encrypted: true, passphraseConfigured: configured };
 }
 
 // Pairing gate: if the iOS app wrote `.health-pair.json`, the configured PAIRING_SECRET must
@@ -103,8 +153,9 @@ export function readJSONCached(file, fallback) {
   const stamp = `${st.mtimeMs}:${st.size}`;
   const hit = _memo.get(file);
   if (hit && hit.stamp === stamp) return hit.value;
-  const value = readJSON(file, fallback);
-  _memo.set(file, { stamp, value });
+  const info = {};
+  const value = readJSON(file, fallback, info);
+  _memo.set(file, { stamp, value, encrypted: !!info.encrypted });
   return value;
 }
 
@@ -149,6 +200,76 @@ export async function loadMetrics() {
 /// invalidated exactly when `readJSONCached` re-reads the file.
 let viewCache = { raw: null, view: Object.create(null) };
 
+/** The cache's `_meta` (schema, app, writtenAt, schemaMinor, recompute), or null. Absent on caches
+ *  written before app 1.2, and in demo mode (no file is read). */
+export function cacheMeta() {
+  if (DEMO || !pairing().ok) return null;
+  const raw = readJSONCached(path.join(DATA_DIR, '.health-cache.json'), {});
+  return raw && typeof raw._meta === 'object' ? raw._meta : null;
+}
+
+// ---- Late-arrival recompute provenance (cache schema minor 1, docs/SCHEMA-CONTRACTS.md s.9) ----
+// The app re-reads only the trailing days on each run. When Apple Health later receives samples
+// dated BEFORE that window (a scale or toothbrush syncing after a gap, a back-logged entry), or
+// samples are deleted, the app rebuilds the affected past days from HealthKit and stamps each one
+// with `r` (when it was rebuilt). Days older than its rebuild cap are not rebuilt; the app records
+// that in `_meta.recompute.capped[metric]` instead of dropping it silently. Everything here is
+// additive: an older cache has neither field and every answer is exactly what it was.
+// A deletion marker has no dates and nothing resolves it, so it expires after this many days
+// (the app drops it on its next write too).
+const DELETION_MARKER_DAYS = 30;
+const markerLive = (c) => !(c?.reason === 'deleted_samples'
+  && (!c.at || Date.parse(c.at) < Date.now() - DELETION_MARKER_DAYS * 86400000));
+const recomputeCapped = (name) => {
+  const c = cacheMeta()?.recompute?.capped?.[name];
+  return c && typeof c === 'object' && markerLive(c) ? c : null;
+};
+
+/** Rebuild provenance for `points` (already filtered to the caller's range) of metric `name`, or
+ *  null when nothing in range was rebuilt and no cap marker applies. `rangeStart`/`rangeEnd` decide
+ *  whether an un-rebuilt (capped) stretch overlaps what the caller asked about. */
+export function recomputeOf(name, points, rangeStart, rangeEnd, explicitStart) {
+  const rebuilt = points.filter((p) => typeof p.r === 'string');
+  const capped = recomputeCapped(name);
+  const capDays = cacheMeta()?.recompute?.capDays ?? null;
+  // A capped marker only matters when the question reaches back before the rebuild window. A
+  // deletion marker has no known dates at all, so it is shown only when the caller explicitly
+  // asked about days before it; otherwise every default-range answer would carry it for ever.
+  const isDeletion = capped?.reason === 'deleted_samples';
+  const cappedApplies = capped
+    && (!isDeletion || (!!explicitStart && !!capped.uncheckedBefore && explicitStart < capped.uncheckedBefore))
+    && (!rangeStart || !capped.uncheckedBefore || rangeStart < capped.uncheckedBefore)
+    && (!rangeEnd || !capped.oldest || rangeEnd >= capped.oldest);
+  if (!rebuilt.length && !cappedApplies) return null;
+  const latest = rebuilt.reduce((a, p) => (a == null || p.r > a ? p.r : a), null);
+  const notes = [];
+  if (rebuilt.length) {
+    notes.push(`${rebuilt.length} day(s) in this range were rebuilt from Apple Health after samples arrived late or were deleted (recomputed_at is the most recent rebuild). Days not listed in rebuiltDays were not touched by a rebuild.`);
+  }
+  if (cappedApplies) {
+    notes.push(capped.reason === 'deleted_samples'
+      ? `Samples were deleted in Apple Health and the app could not tell which days they were on. Days before ${capped.uncheckedBefore} were not re-checked, so they may still include the deleted samples.`
+      : `Samples dated ${capped.oldest ?? '?'} to ${capped.newest ?? '?'} arrived late but are older than the ${capDays ?? 'rebuild'}-day rebuild window, so those days were NOT rebuilt and may be stale. Exporting "Your full history" in the iOS app rebuilds them.`);
+  }
+  return {
+    backfilled_days: rebuilt.length,
+    recomputed_at: latest,
+    ...(rebuilt.length && { rebuiltDays: rebuilt.slice(-31).map((p) => p.d) }),
+    ...(rebuilt.length > 31 && { rebuiltDaysTruncated: rebuilt.length - 31 }),
+    ...(cappedApplies && {
+      capped: {
+        reason: capped.reason ?? 'late_samples',
+        ...(capped.oldest && { oldest: capped.oldest }),
+        ...(capped.newest && { newest: capped.newest }),
+        ...(capped.lastDays != null && { days: capped.lastDays }),
+        ...(capped.uncheckedBefore && { uncheckedBefore: capped.uncheckedBefore }),
+        ...(capped.at && { at: capped.at }),
+      },
+    }),
+    note: notes.join(' '),
+  };
+}
+
 export async function loadWorkouts() {
   if (!pairing().ok) return [];
   if (DEMO) return demoData().workouts;
@@ -229,17 +350,24 @@ function resolveGranularity(pointCount, requested, limit) {
 // averages -- the same rule HealthCache uses on the writing side, so a monthly step total and a
 // monthly resting-HR average both mean what a reader expects.
 function rollUp(points, granularity, cumulative) {
-  if (granularity === 'day') return points.map((p) => ({ date: p.d, value: round(p.v) }));
+  // A day rebuilt after late or deleted samples carries `recomputed_at`; an untouched day carries
+  // nothing extra, so the two are distinguishable point by point (schema minor 1).
+  if (granularity === 'day') {
+    return points.map((p) => ({ date: p.d, value: round(p.v), ...(typeof p.r === 'string' && { recomputed_at: p.r }) }));
+  }
   const buckets = new Map();
   for (const p of points) {
     const k = bucketKey(p.d, granularity);
-    if (!buckets.has(k)) buckets.set(k, []);
-    buckets.get(k).push(p.v);
+    if (!buckets.has(k)) buckets.set(k, { vs: [], rebuilt: 0 });
+    const b = buckets.get(k);
+    b.vs.push(p.v);
+    if (typeof p.r === 'string') b.rebuilt += 1;
   }
-  return [...buckets.entries()].map(([k, vs]) => ({
+  return [...buckets.entries()].map(([k, { vs, rebuilt }]) => ({
     date: k,
     value: round(cumulative ? vs.reduce((a, b) => a + b, 0) : vs.reduce((a, b) => a + b, 0) / vs.length),
     days: vs.length,
+    ...(rebuilt && { backfilled_days: rebuilt }),
   }));
 }
 
@@ -281,8 +409,28 @@ const round = (n) => (n == null ? null : Math.round(n * 1000) / 1000);
 
 export async function status() {
   const p = pairing();
-  const metrics = await loadMetrics();
-  const workouts = await loadWorkouts();
+  let metrics, workouts;
+  try {
+    metrics = await loadMetrics();
+    workouts = await loadWorkouts();
+  } catch (e) {
+    // An encrypted export this server cannot open is reported, not thrown: get_mcp_status is the
+    // tool agents call first, and it is where the fix (the passphrase) has to be spelled out.
+    if (!(e instanceof EnvelopeError)) throw e;
+    return {
+      ok: false,
+      source: sourceLabel(),
+      encrypted: true,
+      encryptionError: e.code,
+      note: e.message,
+      paired: p.required,
+      locked: p.required && !p.ok,
+      metricCount: 0,
+      workoutCount: 0,
+      lastDataDate: null,
+      metrics: [],
+    };
+  }
   const names = Object.keys(metrics);
   let lastDate = null;
   for (const m of Object.values(metrics)) {
@@ -301,12 +449,40 @@ export async function status() {
     }),
     paired: p.required,
     locked: p.required && !p.ok,
+    // Additive: true when the app sealed the export with a passphrase (and this server opened it).
+    encrypted: encryptionStatus().encrypted,
     note: (p.required && !p.ok)
       ? 'Locked: set PAIRING_SECRET to the code shown in the iOS app (Settings → Agent pairing → scan/paste).'
       : undefined,
     metricCount: names.length,
     workoutCount: Array.isArray(workouts) ? workouts.length : 0,
     lastDataDate: lastDate,
+    // Late-arrival recompute (cache schema minor 1). `supported: false` means the app that wrote
+    // this cache predates it: past days are only as fresh as the run that last covered them.
+    recompute: (() => {
+      const meta = cacheMeta();
+      const rec = meta?.recompute ?? null;
+      let rebuiltDays = 0;
+      const rebuiltMetrics = [];
+      for (const [name, m] of Object.entries(metrics)) {
+        const n = (m?.daily || []).filter((p) => typeof p.r === 'string').length;
+        if (n) { rebuiltDays += n; rebuiltMetrics.push(name); }
+      }
+      const capped = Object.entries(rec?.capped ?? {}).filter(([, c]) => markerLive(c)).map(([metric, c]) => ({ metric, ...c }))
+        .sort((x, y) => x.metric.localeCompare(y.metric));
+      return {
+        // A LAN receiver cache has no _meta but does carry `r` stamps pushed by the app.
+        supported: Number(meta?.schemaMinor ?? 0) >= 1 || rebuiltDays > 0,
+        ...(rec?.capDays != null && { capDays: rec.capDays }),
+        ...(rec?.lastRebuiltAt && { recomputed_at: rec.lastRebuiltAt, lastRebuiltDays: rec.lastRebuiltDays ?? null }),
+        backfilled_days: rebuiltDays,
+        ...(rebuiltMetrics.length && { metricsWithRebuiltDays: rebuiltMetrics.sort() }),
+        ...(capped.length && {
+          capped,
+          cappedNote: 'Some late samples (or deletions) affect days older than the app rebuilds per run, so those days may be stale. Data tools flag them per metric; exporting "Your full history" in the iOS app rebuilds them.',
+        }),
+      };
+    })(),
     // Additive: lets an agent see whether a live hourly window exists without calling the tool.
     intraday: (() => {
       const st = intradayStat();
@@ -498,6 +674,8 @@ export async function getHealthMetrics({ metric, start, end, aggregation, granul
       pointsInRange: points.length,
       coverage: coverageOf(m),
     };
+    const rc = recomputeOf(name, points, start || all[0]?.d, end || all[all.length - 1]?.d, start);
+    if (rc) out[name].recompute = rc;
     if (gran !== 'day') {
       out[name].note = `${points.length} daily values rolled up to ${gran}. Narrow start/end, or pass granularity:"day" with a smaller range, for day-level detail.`;
     }
@@ -605,7 +783,13 @@ export async function getTrends({ metric, window = 7, excludeTravelDays } = {})
   const spanStart = Number.isFinite(anchor) ? new Date(priorFrom).toISOString().slice(0, 10) : null;
   const spanEnd = daily.length ? daily[daily.length - 1].d : null;
   const bounds = spanStart && spanEnd ? ev.boundariesIn(spanStart, spanEnd) : null;
+  // Rebuilt days inside the compared span: a trend whose prior window was just rebuilt from late
+  // samples is a different finding from one computed over settled days.
+  const trendRc = Number.isFinite(anchor)
+    ? recomputeOf(metric, daily.filter((p2) => inSpan(p2, priorFrom, anchor)), spanStart, spanEnd)
+    : null;
   return {
+    ...(trendRc && { recompute: trendRc }),
     ...(bounds && bounds.length && {
       segmentBoundaries: bounds,
       segmentNote: ev.SEGMENT_NOTE(bounds.length),
@@ -724,6 +908,13 @@ export async function comparePeriods({ metric, periodA, periodB, anchor, exclude
   const travelA = a[metric]?.excludedDays ?? 0, travelB = b[metric]?.excludedDays ?? 0;
   return {
     metric, unit: a[metric]?.unit || '',
+    // Per side, so an agent can see WHICH period contains rebuilt (or un-rebuilt) days.
+    ...((a[metric]?.recompute || b[metric]?.recompute) && {
+      recompute: {
+        ...(a[metric]?.recompute && { periodA: a[metric].recompute }),
+        ...(b[metric]?.recompute && { periodB: b[metric].recompute }),
+      },
+    }),
     ...(anchorInfo && { anchor: anchorInfo }),
     ...(bounds.length && {
       segmentBoundaries: bounds,
@@ -820,11 +1011,19 @@ export async function getStructuredExport({ metrics: names, start, end, granular
     const rolled = rollUp(points, gran, !!m.cumulative);
     // Stop BEFORE exceeding the budget, so a page is never half a metric.
     if (used > 0 && used + rolled.length > cap) break;
+    const rc = recomputeOf(name, points, start || m.daily?.[0]?.d, end || m.daily?.[m.daily.length - 1]?.d, start);
     data[name] = {
       unit: m.unit || '', cumulative: !!m.cumulative, granularity: gran,
-      daily: rolled.map((p) => ({ d: p.date, v: p.value })),
+      // `r` mirrors the cache's own per-day key: present only on days rebuilt after late or
+      // deleted samples (rolled-up buckets carry a count instead).
+      daily: rolled.map((p) => ({
+        d: p.date, v: p.value,
+        ...(p.recomputed_at && { r: p.recomputed_at }),
+        ...(p.backfilled_days && { backfilled_days: p.backfilled_days }),
+      })),
       pointsInRange: points.length,
       coverage: coverageOf(m),
+      ...(rc && { recompute: rc }),
     };
     used += rolled.length;
   }

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "health-export-ai",
   "display_name": "MetricBridge",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Query your Apple Health data, exported by the MetricBridge iOS app to iCloud Drive, from any MCP agent. Local-first, read-only, zero dependencies.",
   "long_description": "A zero-dependency MCP server that exposes 190 Apple Health metrics (exported by the MetricBridge iOS app into an iCloud Drive folder) to any MCP-compatible agent: Claude Desktop, opencode, Cursor, OpenClaw, Hermes. No bridge, no Docker, no HTTP receiver: the server reads the synced cache file directly over stdio. 14 tools: get_mcp_status, list_metrics, get_health_metrics, get_trends, compare_periods, get_structured_export, get_intraday, query_health_data, list_events, get_profile, get_workouts, get_sleep_sessions, get_cycle_context, correlate_metrics. Plus 22 MCP prompts and a --demo mode with a synthetic dataset. Get the companion iOS app on the App Store: https://apps.apple.com/app/id6784185201",
   "author": {
@@ -32,7 +32,8 @@
       ],
       "env": {
         "HEALTH_DATA_DIR": "${user_config.health_data_dir}",
-        "PAIRING_SECRET": "${user_config.pairing_secret}"
+        "PAIRING_SECRET": "${user_config.pairing_secret}",
+        "HEALTH_EXPORT_PASSPHRASE": "${user_config.export_passphrase}"
       }
     }
   },
@@ -109,6 +110,13 @@
       "description": "If you turned on Agent pairing in the iOS app (Settings → Agent pairing), paste the code here. Leave blank if pairing is off.",
       "required": false,
       "sensitive": true
+    },
+    "export_passphrase": {
+      "type": "string",
+      "title": "Export passphrase (optional)",
+      "description": "Only if you turned on Export encryption in the iOS app (Settings > Export encryption): the same passphrase. It decrypts your exports on this computer and is never sent anywhere. Leave blank if encryption is off.",
+      "required": false,
+      "sensitive": true
     }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "health-export-mcp",
   "mcpName": "io.github.PhilipAD/health-export-mcp",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "type": "module",
   "description": "Open-source, zero-dependency Model Context Protocol (MCP) server to query Apple Health / HealthKit data (190 metrics) from Claude, ChatGPT, Cursor, OpenClaw, Hermes and any MCP agent.",
   "keywords": [
@@ -36,6 +36,7 @@
     "healthstore.mjs",
     "receiver.mjs",
     "events.mjs",
+    "envelope.mjs",
     "prompts.mjs",
     "demo.mjs",
     "apply-mcp-config.mjs",

package/receiver.mjs

@@ -24,6 +24,7 @@ import path from 'node:path';
 import os from 'node:os';
 import net from 'node:net';
 import { fileURLToPath } from 'node:url';
+import { isEnvelope, openEnvelopeJSON, sealEnvelope, parseHeader, configuredPassphrase, EnvelopeError } from './envelope.mjs';
 
 const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 const MAX_BODY = 64 * 1024 * 1024;
@@ -34,16 +35,26 @@ const log = (...a) => process.stderr.write('[receiver] ' + a.map(String).join('
 function expandTilde(p) {
   return (p === '~' || p.startsWith('~/')) ? path.join(os.homedir(), p.slice(1)) : p;
 }
-function readJSON(file, fb) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fb; } }
 // The merge base for an accumulated cache. ABSENT means start fresh; PRESENT-BUT-CORRUPT
 // must never become {} and overwrite the whole history — quarantine it, then start fresh.
-function readMergeBase(file, fb) {
-  if (!fs.existsSync(file)) return fb;
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
-  catch { try { const bak = `${file}.corrupt-${process.pid}`; fs.renameSync(file, bak); log(`quarantined unreadable ${file} -> ${bak}`); } catch {} return fb; }
+//
+// Returns { value, sealedLike } where sealedLike is the envelope header when the existing cache was
+// encrypted (the receiver's directory can be the same iCloud folder the app seals into): the merged
+// result is then written back sealed under the SAME salt, so the app (which holds only the key for
+// that salt) can still read it and nothing is left behind in plaintext. An envelope this receiver
+// cannot open THROWS: quarantining it would restart a perfectly good history from one push.
+function readMergeBase(file, fb, passphrase) {
+  if (!fs.existsSync(file)) return { value: fb, sealedLike: null };
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { try { const bak = `${file}.corrupt-${process.pid}`; fs.renameSync(file, bak); log(`quarantined unreadable ${file} -> ${bak}`); } catch {} return { value: fb, sealedLike: null }; }
+  if (!isEnvelope(parsed)) return { value: parsed, sealedLike: null };
+  return { value: openEnvelopeJSON(parsed, passphrase), sealedLike: parseHeader(parsed) };
 }
 const isLoopback = (h) => h === '127.0.0.1' || h === '::1' || h === 'localhost';
 
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+
 // Validate/sanitise a pushed summary so a malicious LAN client can't poison the agent's context.
 function sanitize(incoming) {
   const out = {};
@@ -58,7 +69,11 @@ function sanitize(incoming) {
       if (!p || typeof p.d !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(p.d)) continue;
       const v = Number(p.v);
       if (!Number.isFinite(v)) continue;
-      daily.push({ d: p.d, v });
+      // `r`: the app rebuilt this past day after late-arriving samples (cache schema minor 1).
+      // Kept only when it is a plain ISO 8601 instant, so a pushed payload cannot smuggle anything
+      // else through to what the MCP server reads.
+      const r = typeof p.r === 'string' && ISO_INSTANT.test(p.r) ? p.r : null;
+      daily.push(r ? { d: p.d, v, r } : { d: p.d, v });
     }
     if (!daily.length) continue;
     out[name] = { unit: typeof m.unit === 'string' ? m.unit.slice(0, 32) : '', cumulative: !!m.cumulative, daily };
@@ -87,7 +102,7 @@ function sanitizeAuthoritative(incoming) {
 // `HealthCache.merge(_:_:authoritativeDays:authoritativeMetrics:)`; without it a LAN-only cache
 // kept deletions and TZ ghost days forever. Metrics not listed (e.g. sensitive types excluded from
 // the run) are never pruned. `yyyy-MM-dd` is fixed-width, so string order IS chronological.
-function mergeCache(existing, incoming) {
+export function mergeCache(existing, incoming) {
   const merged = { ...(existing || {}) };
   const cleaned = sanitize(incoming);
   const auth = sanitizeAuthoritative(incoming);
@@ -106,24 +121,36 @@ function mergeCache(existing, incoming) {
   }
 
   for (const [name, m] of Object.entries(cleaned)) {
-    const byDay = new Map((merged[name]?.daily || []).map((p) => [p.d, p.v]));
+    // A day keeps its recompute stamp (`r`) across later pushes that re-send the same value without
+    // one, matching HealthCache.merge on the app side; a newer stamp replaces it.
+    const byDay = new Map((merged[name]?.daily || []).map((p) => [p.d, p]));
     if (auth && auth.metrics.has(name)) {
       const incomingDays = new Set(m.daily.map((p) => p.d));
       for (const d of [...byDay.keys()]) if (inRange(d) && !incomingDays.has(d)) byDay.delete(d);
     }
-    for (const p of m.daily) byDay.set(p.d, p.v);
+    for (const p of m.daily) {
+      const prev = byDay.get(p.d);
+      const keep = !p.r && typeof prev?.r === 'string' && prev.v === p.v;
+      byDay.set(p.d, keep ? { ...p, r: prev.r } : p);
+    }
     merged[name] = { unit: m.unit || merged[name]?.unit || '', cumulative: !!m.cumulative,
-      daily: [...byDay.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([d, v]) => ({ d, v })) };
+      daily: [...byDay.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([d, p]) => (typeof p.r === 'string' ? { d, v: p.v, r: p.r } : { d, v: p.v })) };
   }
   return merged;
 }
 
-function writeCache(dir, json) {
+function writeCache(dir, json, passphrase = configuredPassphrase()) {
   const file = path.join(dir, '.health-cache.json');
   const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;  // unique → no concurrent-write race
   fs.mkdirSync(dir, { recursive: true });
-  const merged = mergeCache(readMergeBase(file, {}), json);
-  fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
+  const base = readMergeBase(file, {}, passphrase);
+  const merged = mergeCache(base.value, json);
+  const text = JSON.stringify(merged, null, 2);
+  const out = base.sealedLike
+    ? JSON.stringify(sealEnvelope(text, passphrase, { salt: base.sealedLike.salt, iter: base.sealedLike.iter }))
+    : text;
+  fs.writeFileSync(tmp, out, { mode: 0o600 });
   fs.renameSync(tmp, file);
   log(`merged ${Object.keys(sanitize(json)).length} -> ${Object.keys(merged).length} metrics in ${file}`);
   return Object.keys(merged).length;
@@ -135,7 +162,12 @@ export function startReceiver({
   host = process.env.HEALTH_LISTEN_HOST || '127.0.0.1',
   port = Number(process.env.HEALTH_LISTEN_PORT || 27184),
   token = process.env.HEALTH_LISTEN_TOKEN || '',
-  onCache = (json) => writeCache(dir, json),
+  // The default merge uses the same passphrase source as the push decrypt below (the merge base
+  // can itself be sealed when this directory is the folder the app encrypts into).
+  onCache = (json) => writeCache(dir, json, passphrase()),
+  // A function, read per request: the environment is the source in production, tests inject one.
+  passphrase = () => configuredPassphrase(),
+  requireEncrypted = () => process.env.HEALTH_REQUIRE_ENCRYPTED === '1',
 } = {}) {
   // Fail closed: never expose an unauthenticated write endpoint on the network.
   if (!isLoopback(host) && !token) {
@@ -185,6 +217,22 @@ export function startReceiver({
         try { parsed = JSON.parse(body); }
         catch (e) { return json(res, 400, { ok: false, hae: true, error: 'invalid JSON' }); }   // 400 = parse only
         if (parsed && parsed._test === true) return json(res, 200, { ok: true, hae: true, test: true }); // probe: never touch the cache
+        // HEALTH_REQUIRE_ENCRYPTED=1: refuse plaintext pushes. The pairing token travels in a plain
+        // http header on this leg, so anyone who sniffed one push could otherwise forge plaintext
+        // data with it; requiring envelopes means a forger also needs the passphrase.
+        if (requireEncrypted() && !isEnvelope(parsed)) {
+          return json(res, 422, { ok: false, hae: true, reason: 'encryption_required', error: 'this receiver only accepts encrypted pushes' });
+        }
+        // Encrypted push (the app's "Local network" encryption switch). 422 + a machine `reason`
+        // the app turns into a sentence that says where to fix it. Never echoes the passphrase.
+        if (isEnvelope(parsed)) {
+          try { parsed = openEnvelopeJSON(parsed, passphrase()); }
+          catch (e) {
+            const reason = e instanceof EnvelopeError ? e.code : 'malformed';
+            log('encrypted push refused:', reason);
+            return json(res, 422, { ok: false, hae: true, reason, error: e instanceof EnvelopeError ? e.message : 'could not decrypt' });
+          }
+        }
         try { const n = onCache(parsed); json(res, 200, { ok: true, hae: true, metrics: n }); }
         catch (e) { log('write failed', e.message); json(res, 500, { ok: false, hae: true, error: 'write failed: ' + (e.code || e.message) }); } // 500 = disk/write
       });
@@ -218,7 +266,13 @@ export function startReceiver({
       if (opcode === 0xa) { buf = Buffer.alloc(0); return; }     // pong → ignore
       const msg = decodeTextFrame(buf);
       if (msg === null) return;                                  // incomplete or unsupported → wait
-      try { const n = onCache(JSON.parse(msg)); socket.write(encodeTextFrame(JSON.stringify({ ok: true, metrics: n }))); }
+      try {
+        let parsedMsg = JSON.parse(msg);
+        if (requireEncrypted() && !isEnvelope(parsedMsg)) throw new Error('plaintext push refused (HEALTH_REQUIRE_ENCRYPTED)');
+        if (isEnvelope(parsedMsg)) parsedMsg = openEnvelopeJSON(parsedMsg, passphrase());
+        const n = onCache(parsedMsg);
+        socket.write(encodeTextFrame(JSON.stringify({ ok: true, metrics: n })));
+      }
       catch (e) { log('bad WS json', e.message); socket.write(encodeTextFrame(JSON.stringify({ ok: false }))); }
       socket.end();
     });

package/server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/PhilipAD/health-export-mcp",
     "source": "github"
   },
-  "version": "1.4.4",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "health-export-mcp",
-      "version": "1.4.4",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       }

package/server.mjs

@@ -21,7 +21,7 @@ import * as ev from './events.mjs';
 import { PROMPTS } from './prompts.mjs';
 import { DEMO } from './demo.mjs';
 
-const SERVER = { name: 'health-export-ai', version: '1.4.4' };
+const SERVER = { name: 'health-export-ai', version: '1.5.0' };
 const DEFAULT_PROTOCOL = '2025-06-18';
 const log = (...a) => process.stderr.write('[mcp] ' + a.join(' ') + '\n');
 
@@ -57,7 +57,7 @@ const ANNOTATIONS = { readOnlyHint: true, idempotentHint: true, openWorldHint: f
 const TOOLS = [
   {
     name: 'get_mcp_status',
-    description: 'Health check: data source, how many metrics/workouts are available, which optional context files exist, and the most recent data date. Call this first to confirm the bridge is connected.',
+    description: 'Health check: data source, how many metrics/workouts are available, which optional context files exist, the most recent data date, and a `recompute` summary of past days rebuilt after late-arriving samples (with any days too old to rebuild). Call this first to confirm the bridge is connected.',
     inputSchema: { type: 'object', properties: {} },
     handler: () => store.status(),
   },
@@ -71,7 +71,7 @@ const TOOLS = [
   },
   {
     name: 'get_health_metrics',
-    description: "Get values for a metric (or all metrics) over an optional date range, with an aggregate (avg/sum/min/max/latest). The core data-retrieval tool. Every result carries a `coverage` block giving the metric's real firstDate/lastDate/days: check it before trusting a long window, and note that `aggregate` is always computed over the full range even when `points` are rolled up. Single-metric answers also list any logged point events inside the window as segmentBoundaries.",
+    description: "Get values for a metric (or all metrics) over an optional date range, with an aggregate (avg/sum/min/max/latest). The core data-retrieval tool. Every result carries a `coverage` block giving the metric's real firstDate/lastDate/days: check it before trusting a long window, and note that `aggregate` is always computed over the full range even when `points` are rolled up. Single-metric answers also list any logged point events inside the window as segmentBoundaries. A day the app rebuilt after samples arrived late (or were deleted) carries `recomputed_at`, and a metric with rebuilt or possibly stale past days carries a `recompute` block (backfilled_days, recomputed_at, capped); untouched days carry neither.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -412,9 +412,17 @@ async function doctor() {
     if (!newest || st.mtimeMs > newest.mtimeMs) newest = { name, mtimeMs: st.mtimeMs };
     console.log(`    ${name.padEnd(30)} ${fmtBytes(st.size).padStart(9)}   ${new Date(st.mtimeMs).toISOString()}`);
   }
-  const raw = statFile('.health-cache.json') ? store.readJSONCached(store.dataPath('.health-cache.json'), null) : null;
+  const enc = store.encryptionStatus();
+  console.log(`  encryption:      ${!enc.encrypted ? 'off (plaintext export)' : enc.passphraseConfigured ? 'on, passphrase configured' : 'on, NO PASSPHRASE: set HEALTH_EXPORT_PASSPHRASE to the passphrase from the iOS app'}`);
+  let raw = null;
+  try {
+    raw = statFile('.health-cache.json') ? store.readJSONCached(store.dataPath('.health-cache.json'), null) : null;
+  } catch (e) {
+    console.log(`  cache:           cannot be read: ${e.message}`);
+  }
   const meta = raw?._meta;
-  console.log(`  cache schema:    ${meta?.schema ?? (raw ? '1 (no _meta: pre-1.2 app)' : 'no cache file')}${meta?.app ? ` (app ${meta.app})` : ''}`);
+  console.log(`  cache schema:    ${meta?.schema ?? (raw ? '1 (no _meta: pre-1.2 app)' : 'no cache file')}${meta?.schemaMinor != null ? `.${meta.schemaMinor}` : ''}${meta?.app ? ` (app ${meta.app})` : ''}`);
+  if (meta?.recompute?.capped && Object.keys(meta.recompute.capped).length) console.log(`  recompute:       days older than the ${meta.recompute.capDays ?? '?'}-day rebuild cap may be stale for: ${Object.keys(meta.recompute.capped).sort().join(', ')}`);
   try {
     const metrics = p.ok ? await store.listMetrics() : null;
     if (metrics) {