feat(environment): air quality, pollen and UV per day, locations sealed at rest

Fetch the Open-Meteo air-quality feed (CAMS, domains=auto) with the weather:
17 hourly variables folded into local days by fixed rules (means and maxima
only with 18 of 24 hours, ozone as the highest 8-hour running mean, UV only
with the midday hours), a value the feed did not cover stored as null, never
as zero. Requests are cut into 90-day chunks, newest first, and chunks before
mid 2022 ask for the eight pollutant and index variables only. An air-quality
failure never costs the weather row; the day stays unfetched and the nightly
gap fill (up to 90 days per account, newest first) asks for it again.

Every Open-Meteo request asks an instance-wide budget kept in Postgres first
(500 a minute, 4000 an hour, 8000 a day, weighted by the hosted pricing
rule). A refused request is not sent and the run ends as done with
budget_blocked. OPENMETEO_AIR_QUALITY_URL and ENVIRONMENT_AIR_QUALITY_DISABLED
are honoured; the account switch lives on PATCH /api/environment/preferences.

The home, each dated location period and each stored day keep their coarse
location sealed as one value under healthlog/environment-location/v1. The
writers write the sealed value only, the readers open it and fall back to the
readable columns for rows the free-text encryption backfill has not reached,
and the backfill now seals all three and clears the readable columns. The
backup carries the location readable in a portable file and sealed in a
disaster-recovery file; a restore seals either under the receiving key.

Three correlation channels join the environment family (PM2.5, the ozone
8-hour high, the day's highest pollen count), read through the averaged
same-day window and left empty while air quality is off. The Coach and MCP
gain get_environment: module-gated, clamped to the lookback limit, no
coordinate or place name anywhere, with provenance and the attribution
lines. The settings section gets the switch, the coverage and the newest
day's values; the dashboard shows a quiet chip on a day with high pollen,
a warm night or very poor air. Copernicus and Open-Meteo are credited next
to the values.
This commit is contained in:
Marc-André Bombeck committed 2026-10-08 10:02:39 +02:00
1 parent aca497d9ac
commit 3c98d95a40
73 files changed
+6061 -385

No files matched your search

+114
View File
@@ -0,0 +1,114 @@
/**
* The environment module's coarse locations, sealed at rest (v1.42, #615).
*
* Three places held a location in readable columns: the home on the user row
* (`homeLat` / `homeLon` / `homeLabel`), each dated location period
* (`EnvironmentTravelLocation.lat` / `lon` / `label`), and each stored day
* (`EnvironmentContext.lat` / `lon` / `locationLabel`). Coarse as they are
* (one decimal, about 11 km), a home city and a dated list of trips are still
* a movement profile. From v1.42 each row stores ONE sealed value instead, the
* JSON `{ lat, lon, label }` under AES-256-GCM with the associated-data label
* {@link ENVIRONMENT_LOCATION_AAD}: one decrypt per row, and the three parts
* can never drift apart.
*
* Writers seal through {@link sealLocation}; the readable columns are written
* as null. Readers go through {@link readLocation}: the sealed value when a
* row has one, the readable columns only for a row the boot-time encryption
* backfill (`free-text-encryption-backfill.ts`) has not reached yet. A sealed
* value that does not open reads as no location, with a warning on the
* request's event, and is never replaced by the readable columns.
*
* The coordinates are rounded to the privacy floor BEFORE sealing, so the
* sealed value never carries more precision than the readable column did,
* and nothing that leaves the host (the weather and air-quality requests) is
* ever finer than that.
*/
import { Buffer } from "node:buffer";
import { decryptBytes, encryptBytes } from "@/lib/crypto";
import { ENVIRONMENT_LOCATION_AAD } from "@/lib/crypto/encrypted-columns";
import { roundCoarse } from "@/lib/environment/open-meteo";
import { getEvent } from "@/lib/logging/context";
/** A coarse location as the module uses it. */
export interface CoarseLocation {
lat: number;
lon: number;
label: string;
}
/** Seal a location for one of the three `*Encrypted` location columns. */
export function sealLocation(
location: CoarseLocation,
): Uint8Array<ArrayBuffer> {
const sealed = encryptBytes(
Buffer.from(
JSON.stringify({
lat: roundCoarse(location.lat),
lon: roundCoarse(location.lon),
label: location.label,
}),
"utf8",
),
ENVIRONMENT_LOCATION_AAD,
);
const out = new Uint8Array(new ArrayBuffer(sealed.byteLength));
out.set(sealed);
return out;
}
/**
* Open a sealed location. Throws on a bad key id, a tampered value, or a
* payload that is not a location.
*/
export function openLocation(sealed: Uint8Array): CoarseLocation {
const plain = decryptBytes(Buffer.from(sealed), ENVIRONMENT_LOCATION_AAD);
const parsed = JSON.parse(plain.toString("utf8")) as unknown;
if (
!parsed ||
typeof parsed !== "object" ||
typeof (parsed as CoarseLocation).lat !== "number" ||
typeof (parsed as CoarseLocation).lon !== "number" ||
typeof (parsed as CoarseLocation).label !== "string"
) {
throw new Error("sealed environment location has an unexpected shape");
}
const { lat, lon, label } = parsed as CoarseLocation;
return { lat, lon, label };
}
/**
* The location a row holds: the sealed value first, the legacy readable
* columns only when there is no sealed value. Null when the row holds
* neither (or only part of the readable triple), and null with a warning when
* the sealed value does not open.
*
* `fallbackLabel` stands in for a missing readable label, which the home has
* always allowed (`homeLabel` was nullable from the start).
*/
export function readLocation(
row: {
sealed: Uint8Array | null | undefined;
lat: number | null | undefined;
lon: number | null | undefined;
label: string | null | undefined;
},
fallbackLabel?: string,
): CoarseLocation | null {
if (row.sealed && row.sealed.byteLength > 0) {
try {
return openLocation(row.sealed);
} catch (err) {
getEvent()?.addWarning(
`environment location decrypt failed: ${
err instanceof Error ? err.message : String(err)
}`,
);
return null;
}
}
if (row.lat == null || row.lon == null) return null;
const label = row.label ?? fallbackLabel;
if (label == null) return null;
return { lat: row.lat, lon: row.lon, label };
}