MBombeck · MBombeck · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,7 +6,7 @@ Instructions for AI coding agents (OpenAI Codex, Claude Code, Cursor, etc.) work
 
 **HealthLog** — a personal health-tracking web app (weight, blood pressure, pulse, mood, medication compliance) with Withings integration, moodLog.app sync, Dracula-themed UI, mobile-first PWA design.
 
-**Status**: v1.3.2 — Body composition (Total Body Water + Bone Mass), SSRF-hardened outbound fetches, GHCR multi-arch images (`linux/amd64` + `linux/arm64`) with SLSA provenance + SBOM, pg-boss graceful SIGTERM drain, blocking TypeScript CI, locale-integrity test guard. See GitHub Releases + CHANGELOG.md for the full feature timeline (v1.0 → v1.3).
+**Status**: v1.3.3 — Pulse oximetry (SpO₂) as a first-class measurement type, layered on top of v1.3.2 body composition (TBW + Bone Mass). SSRF-hardened outbound fetches (now also covers Web-Push endpoint + Bearer-scope wildcard handling + IP-geolocation HTTPS-only), GHCR multi-arch images (`linux/amd64` + `linux/arm64`) with SLSA provenance + SBOM, pg-boss graceful SIGTERM drain + audit-log retention purge (GDPR Art. 5(1)(e)), blocking TypeScript CI, locale-integrity test guard. moodLog webhook secret now AES-GCM encrypted at rest. See GitHub Releases + CHANGELOG.md for the full feature timeline (v1.0 → v1.3).
 
 ## Tech Stack
 
@@ -20,7 +20,7 @@ Instructions for AI coding agents (OpenAI Codex, Claude Code, Cursor, etc.) work
 | CSS             | Tailwind             | 4       | CSS-first config (`@import "tailwindcss"` syntax)                       |
 | Data fetching   | TanStack Query       | 5       | Provider in `src/components/providers.tsx`                              |
 | Validation      | Zod                  | v4      | Import as `zod/v4` (not `zod`)                                          |
-| Testing         | Vitest               | latest  | Config in `vitest.config.ts`                                            |
+| Testing         | Vitest               | latest  | Config in `vitest.config.mts`                                           |
 | Package manager | pnpm                 | latest  | **Not** npm or yarn                                                     |
 | Node            | 20.x                 | via nvm |                                                                         |
 | Job queue       | pg-boss              | 12      | Named import `{ PgBoss }`, see gotchas                                  |
@@ -126,8 +126,8 @@ messages/
 ├── de.json                       # German translations (primary UI language)
 └── en.json                       # English translations
 prisma/
-├── schema.prisma                 # Database schema (23 models)
-└── migrations/                   # Migration files (0001–0022; latest: body_composition_metrics)
+├── schema.prisma                 # Database schema (25 models)
+└── migrations/                   # Migration files (0001–0024; latest: oxygen_saturation)
 prisma.config.ts                  # Prisma config (DB URL lives here, NOT in schema)
 public/
 ├── sw.js                         # Service worker (Web Push + offline caching)
@@ -216,7 +216,7 @@ These are hard-won lessons. Ignoring them will cause errors:
 
 ## Database Models (Prisma)
 
-23 models: `User`, `Passkey`, `Session`, `AuthChallenge`, `Measurement`, `Medication`, `MedicationSchedule`, `MedicationIntakeEvent`, `ReminderPhaseConfig`, `TelegramReminderMessage`, `TelegramScheduledDeletion`, `ApiToken`, `WithingsConnection`, `MoodEntry`, `AppSettings`, `Feedback`, `AuditLog`, `NotificationChannel`, `NotificationPreference`, `PushSubscription`, `DataBackup`, `UserAchievement`, `RateLimit`.
+25 models: `User`, `Passkey`, `Session`, `AuthChallenge`, `Measurement`, `Medication`, `MedicationSchedule`, `MedicationIntakeEvent`, `ReminderPhaseConfig`, `TelegramReminderMessage`, `TelegramScheduledDeletion`, `ApiToken`, `WithingsConnection`, `MoodEntry`, `AppSettings`, `Feedback`, `AuditLog`, `NotificationChannel`, `NotificationPreference`, `PushSubscription`, `DataBackup`, `UserAchievement`, `RateLimit`, `Device`, `IdempotencyKey`.
 
 ## When Making Changes
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,136 @@
 # Changelog
 
+## [1.3.3] — 2026-05-08
+
+### Added
+
+- **Pulse oximetry as a first-class measurement type (`OXYGEN_SATURATION`).**
+  Closes the SpO2 part of #109. Migration `0024_oxygen_saturation` extends
+  the `MeasurementType` enum. Plausibility range 50–100% (below 50% is
+  incompatible with sustained life and almost certainly a faulty sensor;
+  upper bound 100% is physical). Default severity bands follow BTS Guideline
+  2017 + ATS clinical practice: green 95–100%, orange 92–94%, red <92% —
+  lower-only concern (the upper orange wing collapses onto greenMax since
+  saturation cannot physically exceed 100%). COPD / chronic-respiratory
+  users with a doctor-set baseline of 88–92% can personalize via the
+  threshold-override UI. Wired through Withings (ScanWatch type 54),
+  measurement form, list, charts, doctor PDF, OpenAPI spec, and i18n (DE +
+  EN). iOS DTO already declared `OXYGEN_SATURATION` from a prior commit;
+  the server enum addition closes the long-standing drift.
+- **Body composition surfaces (TOTAL_BODY_WATER, BONE_MASS, BLOOD_GLUCOSE)
+  in the measurements list filter, badge, mobile icon, edit dialog, and
+  server-rendered doctor-report PDF** — closes the UI side of #109. Root
+  cause was three local maps in `measurement-list.tsx` that drifted from
+  the v1.3 server enum; extracted to `measurement-list-meta.ts` with
+  fail-fast coverage tests so future enum additions are caught at build
+  time. Server-side PDF used a separately-drifted type map vs. the
+  browser-side renderer; both are now in sync.
+- **Effective-range thresholds for `TOTAL_BODY_WATER` and `BONE_MASS`** —
+  severity logic was returning `nominal` for any value because no defaults
+  existed.
+
+### Changed
+
+- **OpenAPI `MeasurementType` enum extended + spec version bumped 1.3.0 →
+  1.3.3** to match the actual app. Spec was lagging by two minor releases.
+- **Withings webhook secret now reads from `X-Withings-Webhook-Secret`
+  header** in preference to the legacy `?secret=…` URL query parameter.
+  Closes the URL-leak-via-access-logs vector flagged in audit C-3. Legacy
+  query-param path is retained for backwards compatibility and emits a
+  Wide Event warning so operators can spot still-using-the-old-flow
+  integrators. Plan: remove the query fallback in 1.4.x once warnings drain.
+- **Idempotency `defaultUserIdResolver` now supports Bearer tokens.**
+  Cookie sessions tried first, then Bearer-token via `hashToken` lookup.
+  Without the Bearer fallback, every iOS / external-ingest retry was
+  hitting the handler again and creating duplicate measurements (audit
+  C-4 — the exact use case `withIdempotency` was built for).
+- **GlitchTip URL stripping** — `reportToGlitchtip` now strips the URL
+  query string before forwarding so Withings legacy `?secret=…` and OAuth
+  `?code=…` callbacks cannot leak via the error tracker (audit H-B7).
+
+### Fixed
+
+- **Migration `0022_body_composition_metrics` unit comment lied** —
+  claimed `TOTAL_BODY_WATER: percent of body weight (%)` while every other
+  surface (validators, Withings client, doctor PDF) treated it as `kg`.
+  Comment corrected to match reality.
+
+### Security
+
+- **Bearer-scope wildcard handling (CRITICAL — V3-1).** `requireAuth()`
+  previously accepted any non-admin token regardless of declared
+  permission scope, so a token with `permissions:["medication:ingest"]`
+  could DELETE the user account. Spec now requires `permissions:["*"]`
+  or the explicit required permission.
+- **Account-deletion completeness (CRITICAL — V3-2 / GDPR Art. 17).**
+  Cascades through `Feedback` + `AuditLog` rows so user-erasure is
+  actually total. Daily retention job sweeps orphaned audit rows after
+  90 days as a defence-in-depth.
+- **Withings webhook secret header migration (audit C-3)**, idempotency
+  Bearer-resolver (audit C-4), GlitchTip URL strip (audit H-B7).
+- **Truthfulness pass on medical citations** — SpO2 normal-range source
+  is now consumer-pulse-oximeter consensus + NICE NG115 + FDA labelling
+  (BTS-2017 was for clinical hypoxaemia thresholds, not consumer
+  monitoring); body-composition metrics are explicitly labelled
+  "bioimpedance-estimated, not DEXA-comparable" in the doctor PDF;
+  TBW citation now references the Watson formula / ICRP Reference Man
+  (was misattributed to ESPEN 2017); steps target now references
+  Saint-Maurice JAMA 2020 (WHO publishes minutes/week, not steps).
+- **SpO2 user-override clamp** — overrides could emit physical
+  impossibilities (e.g. `orangeMax = 100.75`); clamped to METRIC_BOUNDS
+  for SpO2 + BODY_FAT.
+- **moodLog webhook secret encrypted at rest with AES-256-GCM** (V3
+  STILL-V2-C-2). Read path tolerates legacy plaintext rows during the
+  transition window; one-shot startup migration in the worker rotates
+  any leftover plaintext rows.
+- **CSP tightening** — `chatgpt.com` + `api.openai.com` `connect-src`
+  now gated to `/settings/ai/**` (was a global blanket on every page,
+  including `/auth/login` → DOM-XSS exfil channel).
+- **Web-Push subscription endpoint SSRF guard** — `endpoint` now
+  requires HTTPS + passes `isPublicUrl()` (was `z.url()` only).
+  Side-fix: `isPublicUrl()` no longer falsely classifies DNS labels
+  starting with `fc`/`fd` (e.g. `fcm.googleapis.com`) as IPv6
+  unique-local; the IPv6 check is now gated on a colon being present.
+- **IP-geolocation lookup is now HTTPS-only.** Default provider is
+  `ipwho.is` (free, HTTPS, no key). Existing `ip-api.com` plaintext
+  HTTP path leaked auth-event IP + timestamp on every login (GDPR Art.
+  32 + Art. 44). Operators can override via `IP_GEO_LOOKUP_URL` (HTTPS
+  only) or disable entirely with `IP_GEO_LOOKUP_DISABLED=1`.
+- **`/api/ai/test` no longer returns provider error message + body
+  excerpt to the client.** Diagnostics land server-side via Wide Events
+  (annotate); client gets a categorised generic message. Closes provider
+  URL / partial key / internal header leak.
+- **`/api/import` rate-limit added** — 5 imports/hour/user. Was
+  unlimited (bulk-injection vector).
+- **Trusted-proxy XFF semantics** — `getClientIp()` now reads
+  `X-Forwarded-For` right-to-left with a configurable
+  `TRUST_PROXY_HOPS` (default 1, matches typical single-proxy
+  self-host). Closes XFF rotation bypass of per-IP rate-limits.
+- **Audit-log retention job** — `audit_logs` rows older than
+  `AUDIT_LOG_RETENTION_DAYS` (default 365) are purged daily. Closes
+  GDPR Art. 5(1)(e) "storage limitation" gap.
+- **Idempotency cachable-status filter** is now an exported, unit-tested
+  function — pins the do-not-cache contract for 401/403/408/429/5xx.
+- **Bearer mock tightening** in `require-auth-bearer.test.ts` +
+  `idempotency.test.ts`: `apiToken.findUnique` calls are now asserted
+  to use `where: { tokenHash: <hashed> }`, so a regression to raw-token
+  comparison would break the suite immediately.
+
+### Internal
+
+- **Server-side enum drift cousins closed.** Five module-level
+  hardcoded type-arrays in `/api/insights/comprehensive`,
+  `/api/dashboard/summary`, `/api/analytics`, `/lib/insights/general-status`,
+  `/api/import` are now derived from `measurementTypeEnum.options`.
+  External-contract enums extended additively:
+  `/api/measurements/series` (`oxygen`, `totalBodyWater`, `boneMass`),
+  `/api/dashboard/widgets` (`oxygenSaturation`), `DashboardWidgetId` +
+  `DEFAULT_DASHBOARD_LAYOUT`. New coverage test asserts the canonical
+  enum stays the source of truth.
+- **Doctor-PDF text-content tests** — replaced bytes-only "renders body
+  composition rows" theatre with `pdf-parse`-driven assertions on the
+  actual rendered DE + EN labels and values. Adds dev dep `pdf-parse`.
+
 ## [1.3.2] — 2026-04-28
 
 ### Fixed

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -36,7 +36,7 @@ docker compose logs -f app    # Tail app logs
 ## Architecture
 
 - **Next.js 16** App Router with TypeScript strict. Pages are RSC by default; `"use client"` only for interactivity.
-- **Prisma 7** ORM with PostgreSQL (23 models). Uses `PrismaPg` adapter from `@prisma/adapter-pg`. Client singleton at `src/lib/db.ts`. Generated client at `src/generated/prisma/client` (note the `/client` suffix). Prisma config in `prisma.config.ts` (not in schema.prisma).
+- **Prisma 7** ORM with PostgreSQL (25 models). Uses `PrismaPg` adapter from `@prisma/adapter-pg`. Client singleton at `src/lib/db.ts`. Generated client at `src/generated/prisma/client` (note the `/client` suffix). Prisma config in `prisma.config.ts` (not in schema.prisma).
 - **shadcn/ui** components (new-york style) in `src/components/ui/`. Add new ones via `pnpm dlx shadcn@latest add <component>`.
 - **Dracula theme** via CSS variables in `globals.css`. Dark mode is default. Use `--dracula-*` tokens for chart colors.
 - **TanStack Query** for client-side data fetching. Provider in `src/components/providers.tsx`.
@@ -81,7 +81,7 @@ docker compose logs -f app    # Tail app logs
 - `src/lib/validations/` — Zod schemas shared between API + client
 - `src/hooks/` — React hooks (`use-auth`)
 - `messages/de.json` + `messages/en.json` — i18n translations
-- `prisma/schema.prisma` — database schema (23 models)
+- `prisma/schema.prisma` — database schema (25 models)
 - `prisma.config.ts` — Prisma config (DB URL here, not in schema)
 - `public/sw.js` — Service worker for Web Push notifications + offline caching
 - `docs/` — long-form audit notes (`docs/audit/`); end-user docs live in the separate site at https://docs.healthlog.dev

diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ Most health apps lock your data behind proprietary clouds, push subscriptions, a
 
 ## Key Features
 
-**Health Metrics** -- Track weight, blood pressure, pulse, body fat, sleep, steps, blood glucose (fasting/postprandial/random/bedtime, mg/dL ↔ mmol/L), total body water, and bone mass with interactive trend charts, moving averages, and traffic-light ranges based on ESC/ESH 2018 and ADA 2024 guidelines. Body-composition metrics sync automatically from Withings Body+ scales.
+**Health Metrics** -- Track weight, blood pressure, pulse, body fat, sleep, steps, blood glucose (fasting/postprandial/random/bedtime, mg/dL ↔ mmol/L), total body water, bone mass, and pulse oximetry (SpO₂) with interactive trend charts, moving averages, and traffic-light ranges based on ESC/ESH 2018, ADA 2024, and consensus pulse-oximeter guidance (NICE NG115). Body-composition + SpO₂ metrics sync automatically from Withings Body+ scales and ScanWatch devices.
 
 **Custom Thresholds** -- Override the computed default ranges per metric with the targets your clinician set. Audit-logged. Doctor Report PDF prints both your target and the standard reference.
 
@@ -102,7 +102,7 @@ Open **http://localhost:3000**. The first registered user becomes admin.
 | ------------- | ------------------------------------------------- |
 | Framework     | Next.js 16 (App Router, React Server Components)  |
 | Language      | TypeScript (strict mode)                          |
-| Database      | PostgreSQL 16 + Prisma 7 (23 models)              |
+| Database      | PostgreSQL 16 + Prisma 7 (25 models)              |
 | Job Queue     | pg-boss 12 (reminders, insights, backups)         |
 | UI            | shadcn/ui, Tailwind CSS 4, Radix UI, Lucide Icons |
 | Charts        | Recharts 3                                        |

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
@@ -2,10 +2,11 @@ openapi: 3.1.0
 
 info:
   title: HealthLog API
-  version: 1.3.0
+  version: 1.3.3
   description: |
     REST API for HealthLog — a personal health-tracking PWA covering weight,
-    blood pressure, pulse, mood, medication compliance, blood glucose, and
+    blood pressure, pulse, mood, medication compliance, blood glucose, body
+    composition (total body water + bone mass), pulse oximetry (SpO2), and
     sleep. The same API powers the Next.js web client and the native iOS
     client.
 
@@ -3295,10 +3296,13 @@ components:
         Long-lived API token issued via `POST /api/tokens`. Accepted on all
         user endpoints (interchangeable with the session cookie) and required
         on external ingest endpoints (e.g. `/api/ingest/medication`). Tokens
-        are prefixed `hlk_` and stored as SHA-256 hashes server-side. Bearer
-        tokens never grant admin access — admin routes require the session
-        cookie. Permission scopes are enforced from the token's `permissions`
-        array.
+        are prefixed `hlk_` and stored as HMAC-SHA-256 hashes server-side
+        (keyed with `API_TOKEN_HMAC_KEY` so a DB dump alone does not allow
+        precomputed-rainbow lookups). Bearer tokens never grant admin access
+        — admin routes require the session cookie. Permission scopes are
+        enforced from the token's `permissions` array; a token MUST declare
+        either the explicit required permission for the route or the
+        wildcard `"*"`.
     sessionCookie:
       type: apiKey
       in: cookie
@@ -3442,6 +3446,9 @@ components:
         - SLEEP_DURATION
         - ACTIVITY_STEPS
         - BLOOD_GLUCOSE
+        - TOTAL_BODY_WATER
+        - BONE_MASS
+        - OXYGEN_SATURATION
 
     MeasurementSource:
       type: string
@@ -4730,6 +4737,11 @@ components:
         glitchtipEnvironment: { type: [string, 'null'] }
 
     # ─── iOS adapter DTOs (v1.3) ──────────────────────────────
+    # Used by /api/dashboard/summary (`MetricCard.kind`) and the
+    # /api/measurements/series adapter. Extended in v1.3.3 to cover the
+    # body-composition + SpO2 measurements that the server already emits.
+    # iOS clients SHOULD decode unknown values defensively; we still
+    # publish the canonical list here so generated codecs stay accurate.
     MetricKind:
       type: string
       enum:
@@ -4740,6 +4752,9 @@ components:
         - glucose
         - sleep
         - steps
+        - totalBodyWater
+        - boneMass
+        - oxygenSaturation
 
     InsightSeverityIos:
       type: string

diff --git a/messages/de.json b/messages/de.json
@@ -91,6 +91,7 @@
     "typeSteps": "Aktivität (Schritte)",
     "typeTotalBodyWater": "Gesamtkörperwasser",
     "typeBoneMass": "Knochenmasse",
+    "typeOxygenSaturation": "Sauerstoffsättigung",
     "unitSteps": "Schritte",
     "bmiUnderweight": "Untergewicht",
     "bmiNormal": "Normalgewicht",
@@ -249,6 +250,7 @@
     "typeBloodGlucose": "Blutzucker",
     "typeTotalBodyWater": "Gesamtkörperwasser",
     "typeBoneMass": "Knochenmasse",
+    "typeOxygenSaturation": "Sauerstoffsättigung",
     "glucoseContext": "Kontext",
     "glucoseContextFasting": "Nüchtern (≥8 h ohne Nahrung)",
     "glucoseContextPostprandial": "Postprandial (2 h nach dem Essen)",
@@ -538,6 +540,9 @@
     "pointsAllTitle": "Alle verfügbaren Messpunkte",
     "systolic": "Systolisch",
     "diastolic": "Diastolisch",
+    "bodyWater": "Körperwasser",
+    "boneMass": "Knochenmasse",
+    "spo2": "SpO₂",
     "movingAverage7d": "7T-Schnitt",
     "avg7dShort": "7T",
     "avg30dShort": "30T",
@@ -760,6 +765,9 @@
     "metricGlucosePostprandial": "Glukose — postprandial",
     "metricGlucoseRandom": "Glukose — beliebig",
     "metricGlucoseBedtime": "Glukose — vor dem Schlafen",
+    "metricBodyWater": "Körperwasser",
+    "metricBoneMass": "Knochenmasse",
+    "metricOxygenSaturation": "Sauerstoffsättigung (SpO₂)",
     "unsetExplanation": "Kein eigener Wert — berechneter Default aktiv.",
     "loadError": "Zielwerte konnten nicht geladen werden"
   },