docs: Struktur .claude/docs versionieren, working/, Gitea-Index, Regeln

- .gitignore: .claude/docs, rules, commands tracken; settings.local weiter ignorieren
- DOCUMENTATION.md: verbindliche Ablage functional/technical/working/issues
- .claude/README.md: Agent-Einstieg; GITEA_ISSUES_INDEX aus MCP (Stand 2026-04-08)
- Arbeitspapiere von docs/ nach .claude/docs/working/ verschoben
- docs/MEMBERSHIP_SYSTEM.md als Stub; kanonisch technical/MEMBERSHIP_SYSTEM.md
- CLAUDE.md Pflichtlektüre und Links angepasst; docs/README.md vereinfacht

Made-with: Cursor
This commit is contained in:
Lars committed 2026-04-08 13:01:49 +02:00
1 parent 24daeeb83c
commit 7940dc7560
115 files changed
+45622 -1063

No files matched your search

@@ -0,0 +1,186 @@
# Code-Audit Mitai Jinkendo
| Feld | Wert |
|------|------|
| **Datum** | 2026-04-04 |
| **Bezeichnung** | Vollständige Code-Analyse (Backend FastAPI, Frontend React, Konfiguration) |
| **Umfang** | Stichproben + gezielte Suche (Security-Patterns, Auth, SQL, Hardcoding, Duplikate) |
| **Einschränkung** | Kein Penetrationstest, keine Laufzeit-Fuzzing-Tests; statische Analyse und Architektur-Review |
---
## Kurzfassung
Die Codebasis ist insgesamt strukturiert (modulare Router, parametrisierte SQL-Queries, bcrypt, Rate-Limits auf sensiblen Auth-Endpunkten). Es gibt jedoch **kritische Autorisierungslücken** rund um `X-Profile-Id` und die öffentlichen `/api/profiles`-Routen sowie eine **fehlende Objekt-Zuordnung bei Foto-Downloads**. Zusätzlich fallen **Konfigurations- und Versions-Inkonsistenzen**, **Legacy-/Duplikat-Code** und **Abweichungen von den eigenen Coding Rules** (direktes `fetch` im Frontend) auf.
**Gitea-Issue-Vorlagen** für die wichtigsten Punkte liegen unter `gitea/`.
---
## Kritisch (P0) – Sicherheit
### 1. `X-Profile-Id` ohne Abgleich mit der Session (`get_pid`)
**Datei:** `backend/routers/profiles.py` (Hilfsfunktion `get_pid`)
```20:29:backend/routers/profiles.py
def get_pid(x_profile_id: Optional[str] = Header(default=None)) -> str:
"""Get profile_id - from header for legacy endpoints."""
if x_profile_id:
return x_profile_id
with get_db() as conn:
cur = get_cursor(conn)
cur.execute("SELECT id FROM profiles ORDER BY created LIMIT 1")
row = cur.fetchone()
if row: return row['id']
raise HTTPException(400, "Kein Profil gefunden")
```
Ist der Header gesetzt, wird **jede** authentifizierte Session auf die **beliebig gewählte** Profil-ID umgebogen. `get_pid` wird in zahlreichen Routern genutzt (Gewicht, Aktivität, Ernährung, Fotos-Upload/Liste, Vitals, Insights, …). Ein Angreifer mit gültigem Nutzer-Token kann damit **fremde Daten lesen und schreiben** (klassische IDOR-Schwachstelle).
**Empfehlung:** Profil-Kontext ausschließlich aus `session['profile_id']` ableiten; `X-Profile-Id` nur für **Admins** erlauben und gegen eine explizite Admin-Prüfung validieren – oder entfernen, wenn nicht mehr benötigt.
**Vorlage:** `gitea/TEMPLATE_P0-profile-scoping-x-profile-id.md`
---
### 2. `/api/profiles`-Endpunkte ohne Admin-Pflicht
**Datei:** `backend/routers/profiles.py`
Endpunkte wie `GET/POST /api/profiles`, `GET/PUT/DELETE /api/profiles/{pid}` nutzen `Depends(require_auth)`, **nicht** `require_admin`. Damit kann jeder eingeloggte Nutzer u. a. **alle Profile auflisten**, **Profildaten abrufen** und unter Umständen **Profile löschen** (wenn mehr als eines existiert).
Das Frontend nutzt `GET /api/profiles` in `ProfileContext.jsx` für die Profilliste – funktional erklärbar, **sicherheitstechnisch** aber nur akzeptabel, wenn ausschließlich Admins je Instanz ein Konto haben (Annahme, die im Code nicht erzwungen wird).
**Empfehlung:** Öffentliche/„current user“-API von Admin-CRUD trennen; Listen/Löschen/Anlegen fremder Profile nur mit `require_admin` und expliziter Policy.
**Vorlage:** `gitea/TEMPLATE_P0-profiles-router-authorization.md`
---
### 3. Foto-Abruf ohne Profil-Ownership-Prüfung
**Datei:** `backend/routers/photos.py` – `GET /api/photos/{fid}`
Die Route lädt die Datei nur anhand der Foto-`id`, **ohne** zu prüfen, ob `photos.profile_id` zur Session passt. UUIDs erschweren Raten, bieten aber **keinen** Zugriffsschutz, wenn IDs bekannt sind oder geleakt werden.
**Empfehlung:** `SELECT ... WHERE id=%s AND profile_id=%s` mit `session['profile_id']` (bzw. adminseitig explizite Ausnahme).
**Vorlage:** `gitea/TEMPLATE_P1-photo-ownership-enforcement.md`
---
## Hoch (P1)
### 4. CORS: Default `allow_origins=["*"]`
**Datei:** `backend/main.py`
Wenn `ALLOWED_ORIGINS` nicht gesetzt ist, erlaubt die Middleware **`'*'`** in Kombination mit `allow_credentials=True`. Das ist in Browsern problematisch (kann je nach Client zu unerwartetem Verhalten führen) und in Produktion **riskant**, falls die Umgebungsvariable fehlt.
**Empfehlung:** In Produktion kein Wildcard-Default; Startfehler oder restriktive Default-Liste für Dev dokumentieren.
**Vorlage:** `gitea/TEMPLATE_P1-cors-allowed-origins-hardening.md`
---
### 5. Session-Token in der URL (Fotos)
**Datei:** `frontend/src/utils/api.js` – Foto-URL mit `?token=...` für `<img>`-Tags; Backend: `require_auth_flexible` mit Query-Parameter.
Token in URLs landen in **Logs, Referer, Browser-Historie** – erhöhtes Leak-Risiko.
**Empfehlung:** Kurzlebige signierte URLs, Cookie-Session für Same-Origin, oder dedizierter Download-Endpoint mit Header-Auth und Blob-URL im Frontend (mit Aufwand abzuwägen).
---
### 6. Veraltete / widersprüchliche Versionsangaben
| Ort | Befund |
|-----|--------|
| `backend/main.py` | `FastAPI(..., version="3.0.0")` – wirkt wie API-/Framework-Version, nicht App-Version |
| `backend/version.py` | `APP_VERSION = "0.9l"` |
| `backend/routers/auth.py` `/api/auth/status` | `"version": "v9b"` – offensichtlich veraltet |
| `CLAUDE.md` | erwähnt `frontend/src/version.js` – **Datei im Repo nicht vorhanden** (Dokumentationsdrift) |
**Empfehlung:** Eine Quelle (`version.py` + optional Endpoint `/api/version`), Frontend aus derselben Quelle oder Build-Inject.
---
## Mittel (P2) – Inkonsistenzen & Wartung
### 7. Frontend: direktes `fetch` statt `api.js`
Laut `.claude/rules/CODING_RULES.md` sollen alle API-Calls über `api.js` laufen. Tatsächlich gibt es u. a.:
- `frontend/src/context/AuthContext.jsx`, `ProfileContext.jsx`, `PasswordRecovery.jsx`
- `frontend/src/pages/AdminPanel.jsx`, `SettingsPage.jsx`
Risiko: inkonsistente Header/Fehlerbehandlung, schwerer zu auditieren.
**Vorlage:** `gitea/TEMPLATE_P2-consolidate-api-client.md`
---
### 8. Duplikat- und Legacy-Code
| Befund | Hinweis |
|--------|---------|
| `backend/main_old.py` | Großes, nicht eingebundenes Modul – verwirrt Reviews und Suche |
| `backend/calculations/*` vs `backend/data_layer/*` | Parallelstruktur; Phase-0c nutzt `data_layer`, aber z. B. `placeholder_resolver.py` importiert noch `calculations.scores` |
| `backend/apply_v9c_migration.py` in `startup_event` | Legacy-Hook neben `db_init` – technische Schuld |
**Vorlage:** `gitea/TEMPLATE_P2-dead-code-and-metrics-dedup.md`
---
### 9. Hardcodierte Werte (Auswahl)
- **Tests:** `tests/dev-smoke-test.spec.js` – Fallback-Passwort `'5112'` wenn `TEST_PASSWORD` fehlt (nur für lokale/CI-Umgebung akzeptabel, sollte in Doku stehen und nie in Prod-Daten).
- **Playwright:** `playwright.config.js` – feste `baseURL: 'https://dev.mitai.jinkendo.de'`.
- **Admin-UI:** `AdminPanel.jsx` – Beispielzeile mit `APP_URL=http://192.168.2.49:3002` (Dokumentation im UI).
- **Farben:** Viele Hex-Werte in JSX (z. B. `NutritionCharts.jsx`, `History.jsx`) – Verstoß gegen die eigene CSS-Variablen-Regel, aber eher UX/Wartbarkeit als Security.
### 10. Passwortlänge: `/api/auth/pin` vs Registrierung
Registrierung verlangt mindestens **8** Zeichen; PIN-/Passwort-Änderung über `/api/auth/pin` erlaubt **4** Zeichen. Inkonsistent für Sicherheitskommunikation.
### 11. Dynamische SQL-`UPDATE`-Fragmente
Muster `UPDATE ... SET {', '.join(f'{k}=%s' for k in d)}` erscheint in mehreren Routern. **Soweit geprüft**, werden Keys aus kontrollierten Dicts/Pydantic-Modellen gebaut – **kein** offensichtlicher SQL-Injection-Pfad durch Rohtext. Risiko steigt, wenn später unkontrollierte Keys eingespeist werden. Whitelist pro Endpoint wäre robuster.
---
## Positiv hervorgehoben
- Parametrisierte Queries (`%s`) durchgängig üblich; keine `execute(f"...{userinput}")` in den geprüften kritischen Pfaden.
- `bcrypt` + Migration von Legacy-SHA256 in `auth.py` / Login.
- Rate Limiting auf Login, Forgot-Password, Register (`slowapi`).
- Forgot-Password gibt keine E-Mail-Existenz preis.
- Admin-Router (`/api/admin/*`) konsequent mit `require_admin`.
- Modulare Router-Registrierung in `main.py`.
---
## Mapping: Vorlagen → Themen
| Priorität | Thema | Datei unter `gitea/` |
|-----------|--------|----------------------|
| P0 | IDOR `X-Profile-Id` / `get_pid` | `TEMPLATE_P0-profile-scoping-x-profile-id.md` |
| P0 | `/api/profiles` ohne Admin | `TEMPLATE_P0-profiles-router-authorization.md` |
| P1 | Foto-Ownership | `TEMPLATE_P1-photo-ownership-enforcement.md` |
| P1 | CORS-Default | `TEMPLATE_P1-cors-allowed-origins-hardening.md` |
| P2 | `fetch` vs `api.js` | `TEMPLATE_P2-consolidate-api-client.md` |
| P2 | Legacy/Duplikate | `TEMPLATE_P2-dead-code-and-metrics-dedup.md` |
---
## Nächste Schritte (empfohlen)
1. **Sofort:** P0-Issues planen und `get_pid` / Profil-Router designen (Session-first, Admin-Override explizit).
2. **Kurzfristig:** Foto-GET mit `profile_id`-Check; CORS in allen Umgebungen prüfen.
3. **Mittelfristig:** Versionierung vereinheitlichen; `fetch`-Calls bündeln; `main_old.py` und Metrik-Duplikate bereinigen oder archivieren.
---
*Erstellt im Rahmen einer statischen Code-Analyse; bei Änderungen am Code bitte Report-Datum und Befunde aktualisieren.*
@@ -0,0 +1,8 @@
# Audit 2026-04-04 – Code Review
| Inhalt | Pfad |
|--------|------|
| Vollständiger Report | [`CODE_AUDIT_REPORT_2026-04-04.md`](./CODE_AUDIT_REPORT_2026-04-04.md) |
| Gitea-Issue-Vorlagen (Copy & Paste) | [`gitea/`](./gitea/) |
Beim Anlegen in Gitea: **Titel** und **Labels** aus dem YAML-Kopf der jeweiligen Vorlage übernehmen, **Beschreibung** = Rest des Markdown (ohne die `---`-Blöcke, falls gewünscht).
@@ -0,0 +1,37 @@
---
# Gitea: Beim Anlegen des Issues Titel und Labels manuell übernehmen (YAML wird von Gitea nicht automatisch geparst – dient als Meta-Hinweis).
title: "[Security/P0] X-Profile-Id / get_pid ermöglicht IDOR über alle Datendomänen"
labels: security, backend, priority-critical
---
## Kontext
Code-Audit 2026-04-04 (`/.claude/docs/audit/20260404_code_audit/CODE_AUDIT_REPORT_2026-04-04.md`).
## Problem
Die Funktion `get_pid` in `backend/routers/profiles.py` gibt bei gesetztem Header `X-Profile-Id` diesen Wert **unverändert** zurück, **ohne** Abgleich mit `session['profile_id']` oder Admin-Rolle.
Damit kann jede authentifizierte Session mit gültigem Token Daten eines **beliebigen** Profils über alle Endpunkte ansprechen, die `get_pid(x_profile_id)` nutzen (u. a. Gewicht, Aktivität, Ernährung, Fotos-Upload/Liste, Vitals, Insights, Schlaf, Ruhetage, Export).
## Reproduktion (konzeptionell)
1. Als Nutzer A einloggen, Token erhalten.
2. Profil-ID von Nutzer B ermitteln (z. B. über `GET /api/profiles` – siehe separates Issue).
3. Request gegen geschützten Endpoint mit Header `X-Profile-Id: <uuid-von-B>` und Token von A.
## Erwartetes Verhalten
- Standard: `profile_id` **ausschließlich** aus der Session.
- Optional: `X-Profile-Id` nur für **Admins** und mit expliziter Prüfung `require_admin` + dokumentierter Use-Case (Multi-User-Admin-UI).
## Akzeptanzkriterien
- [ ] Alle betroffenen Router verwenden session-basierte Profil-IDs oder einen validierten Admin-Override.
- [ ] Regressionstests oder manuelle Checkliste für mindestens einen Endpoint pro Router-Gruppe.
- [ ] Kurze Doku in `.claude/rules` oder technischer Doc, ob `X-Profile-Id` noch existiert und wann.
## Betroffene Dateien (Ausgangspunkt)
- `backend/routers/profiles.py` (`get_pid`)
- Alle Importe von `get_pid` (z. B. `weight`, `activity`, `nutrition`, `photos`, `insights`, `vitals_baseline`, `blood_pressure`, `rest_days`, `sleep`, …)
@@ -0,0 +1,37 @@
---
title: "[Security/P0] /api/profiles CRUD ohne require_admin – Datenabfluss und Missbrauch"
labels: security, backend, priority-critical
---
## Kontext
Code-Audit 2026-04-04.
## Problem
In `backend/routers/profiles.py` nutzen u. a. folgende Routen `Depends(require_auth)` **ohne** `require_admin`:
- `GET /api/profiles` – Liste aller Profile
- `POST /api/profiles` – Profil anlegen
- `GET/PUT/DELETE /api/profiles/{pid}` – Abruf/Update/Löschen nach ID
Jeder eingeloggte Nutzer kann damit die Profilliste sehen und je nach Datenbestand auch fremde Profile manipulieren oder löschen (sofern mehr als ein Profil existiert).
Das Frontend (`ProfileContext.jsx`) ruft `GET /api/profiles` für die Profilauswahl auf – das erklärt die aktuelle UX, ersetzt aber keine serverseitige Autorisierung.
## Erwartetes Verhalten
- Listen, Anlegen, Löschen und Bearbeiten **fremder** Profile: nur `require_admin`.
- „Aktuelles Profil“: dedizierte Routen (`/api/profile` o. ä.) strikt an `session['profile_id']` gebunden.
## Akzeptanzkriterien
- [ ] Rollenmodell dokumentiert (wer darf `/api/profiles` sehen?).
- [ ] Admin-only für sensible Operationen erzwungen.
- [ ] Frontend angepasst (falls nötig: Admin vs. normaler Nutzer unterschiedliche Endpunkte).
- [ ] Keine Regression für Single-User-Selfhosting ohne unnötige UX-Brüche (optional: Feature-Flag oder Rolle `admin` für ersten User).
## Betroffene Dateien
- `backend/routers/profiles.py`
- `frontend/src/context/ProfileContext.jsx` (und ggf. weitere Aufrufer von `/api/profiles`)
@@ -0,0 +1,36 @@
---
title: "[Security/P1] CORS: Default ALLOWED_ORIGINS=* mit allow_credentials=True"
labels: security, backend, configuration, priority-high
---
## Kontext
Code-Audit 2026-04-04.
## Problem
`backend/main.py`:
```python
allow_origins=os.getenv("ALLOWED_ORIGINS", "*").split(","),
allow_credentials=True,
```
Fehlt die Umgebungsvariable, ist die Default-Konfiguration `*`. Zusammen mit `allow_credentials=True` ist das in Produktion unerwünscht und erschwert eine klare Security-Posture.
## Erwartetes Verhalten
- Produktion: explizite Origins aus `ALLOWED_ORIGINS` (kommasepariert), kein stiller Wildcard-Fallback.
- Entwicklung: dokumentierter Default (z. B. `http://localhost:5173`) oder explizite Opt-in-Umgebungsvariable `CORS_ALLOW_ALL=true`.
## Akzeptanzkriterien
- [ ] Verhalten in `.env.example` und Deployment-Doku beschrieben.
- [ ] Optional: Anwendung startet nicht, wenn `ALLOWED_ORIGINS` in `ENV=production` fehlt.
- [ ] Manuelle Prüfung: Browser-Requests von fremden Origins werden blockiert.
## Betroffene Dateien
- `backend/main.py`
- `.env.example`
- ggf. `docker-compose*.yml`
@@ -0,0 +1,36 @@
---
title: "[Security/P1] GET /api/photos/{fid} ohne Prüfung auf profile_id (Objekt-Zugriff)"
labels: security, backend, priority-high
---
## Kontext
Code-Audit 2026-04-04.
## Problem
`backend/routers/photos.py`: `GET /{fid}` lädt ein Foto nur anhand der `id` aus der Tabelle `photos`, ohne zu prüfen, ob der Datensatz zu `session['profile_id']` gehört.
Authentifizierung ist vorhanden (`require_auth_flexible`), aber **keine Objekt-Level-Autorisierung**.
## Risiko
Bei bekannter oder erratener Foto-UUID können Inhalte anderer Nutzer derselben Instanz abgerufen werden.
## Erwartetes Verhalten
```sql
SELECT path FROM photos WHERE id = %s AND profile_id = %s
```
mit `profile_id` aus der Session; Admins optional mit separatem Codepfad.
## Akzeptanzkriterien
- [ ] Abruf nur für eigenes Profil (bzw. dokumentierter Admin-Fall).
- [ ] Bestehende Clients (PWA) unverändert nutzbar.
- [ ] Kurzer Testfall oder manuelle Prüfung: Nutzer A kann Foto von B nicht öffnen.
## Betroffene Dateien
- `backend/routers/photos.py`
@@ -0,0 +1,30 @@
---
title: "[Tech-Debt/P2] Frontend: direktes fetch statt zentral api.js (Auth, Admin, Import)"
labels: frontend, refactoring, consistency
---
## Kontext
Code-Audit 2026-04-04. Verbindliche Regel: `.claude/rules/CODING_RULES.md` – alle API-Calls über `frontend/src/utils/api.js`.
## Problem
Mehrere Komponenten nutzen natives `fetch('/api/...')` mit manuell gesetztem `X-Auth-Token`, u. a.:
- `frontend/src/context/AuthContext.jsx`
- `frontend/src/context/ProfileContext.jsx`
- `frontend/src/pages/PasswordRecovery.jsx`
- `frontend/src/pages/AdminPanel.jsx`
- `frontend/src/pages/SettingsPage.jsx`
Nachteile: doppelte Fehlerbehandlung, schwerere Wartung, leichter zu übersehen bei Security-Reviews.
## Erwartetes Verhalten
Alle Aufrufe über `api.js` (oder ein einziges dünnes Wrapper-Modul), inkl. Upload/Export-Sonderfälle.
## Akzeptanzkriterien
- [ ] Kein direktes `fetch('/api/` mehr außerhalb von `api.js` (Ausnahmen dokumentieren, falls nötig).
- [ ] Einheitliche Fehler- und 401-Behandlung.
- [ ] Kurze Notiz in CODING_RULES oder LESSONS_LEARNED, falls Ausnahmen bleiben.
@@ -0,0 +1,34 @@
---
title: "[Tech-Debt/P2] Legacy main_old.py, calculations/ vs data_layer/, Startup-Migration-Hooks"
labels: backend, refactoring, maintenance
---
## Kontext
Code-Audit 2026-04-04.
## Problemstellung (Bündel)
1. **`backend/main_old.py`**: große, nicht in `main.py` eingebundene Datei – verwirrt Suche, Reviews und Onboarding.
2. **Parallele Metrik-Pfade**: `backend/data_layer/` (Phase 0c) und `backend/calculations/` existieren nebeneinander; `placeholder_resolver.py` importiert z. B. noch `calculations.scores`.
3. **`startup_event` in `main.py`**: zusätzlicher Hook `apply_v9c_migration` neben `db_init` – Legacy-Pfad neben dem Migrations-System.
## Ziele
- Single Source of Truth für Metriken (klar dokumentiert: `data_layer` vs. verbleibende Hilfsmodule).
- Entfernen oder Archivieren (`docs/archive/` oder Git-History-only) von `main_old.py`, sofern nicht mehr referenziert.
4. Migration-Startup vereinheitlichen (nur `db_init` / nummerierte SQL-Migrationen, sofern v9c-Hook obsolet).
## Akzeptanzkriterien
- [ ] Entscheidung dokumentiert: welches Paket autoritativ ist.
- [ ] Keine doppelten Implementierungen für dieselbe Metrik ohne Grund.
- [ ] `main_old.py` entfernt oder klar als „archived“ markiert und aus IDEs/CI-Suche ausgeschlossen (optional).
- [ ] Build/Start ohne v9c-Sonderpfad, falls redundant.
## Betroffene Pfade (Start)
- `backend/main_old.py`
- `backend/main.py` (startup)
- `backend/data_layer/`, `backend/calculations/`
- `backend/placeholder_resolver.py`