audi-app/homeassistant/INTERNET_ZUGRIFF_EINRICHTEN.md

# Internetzugriff für DataMetric360 einrichten

Schritt-für-Schritt-Anleitung, damit die native Companion-App (iOS-Sideload, siehe
`../COMPANION_APP_ARCHITECTURE.md` §1) von unterwegs (Mobilfunk, fremdes WLAN) funktioniert - nicht nur
im Heimnetz/über Tailscale. Home Assistant selbst bleibt dabei durchgehend **lokal, ohne offenen Port**;
nur ein eng begrenzter, pfad-gefilterter Ausschnitt der API wird über einen Cloudflare-Tunnel erreichbar
gemacht. Architektur/Begründung: `../COMPANION_APP_ARCHITECTURE.md` §4. Die technische Pfad-Freigabeliste
selbst, die in Schritt 4 unten eingetragen wird: [`REVERSE_PROXY.md`](REVERSE_PROXY.md).

**Wer was macht:** Kontoerstellung, Domain-/Nameserver-Verwaltung bei Cloudflare bzw. all-inkl und das
Klicken durch die HA-Add-on-Oberfläche sind ausschließlich Sache des Fahrzeughalters selbst - dafür gibt
es hier keine Automatisierung, nur die genauen Schritte. Alles, was als Datei/Konfiguration vorbereitet
werden konnte, ist bereits fertig (`REVERSE_PROXY.md`s Regeln).

**Voraussetzungen, die bereits erfüllt sind** (nichts davon ist hier noch zu tun):
- `datametric360.de` ist bei all-inkl registriert (siehe `../COMPANION_APP_ARCHITECTURE.md` §5 Punkt 4)
  - eigens dafür, ohne Webseite/Postfach darauf.
- Die companion-app spricht bereits ausschließlich REST/WebSocket gegen eine konfigurierbare
  "Server-Adresse" (kein `hass`-Objekt, kein fest verdrahteter Hostname) - dieser Schritt ändert nur,
  *welche* Adresse dort später eingetragen wird, nicht die App selbst.

---

## 1. Cloudflare-Konto anlegen, Domain hinzufügen

1. Auf [cloudflare.com](https://cloudflare.com) ein (kostenloses) Konto anlegen.
2. Im Dashboard *Add a Site* → `datametric360.de` eingeben.
3. Plan **Free** wählen - reicht vollständig aus (Tunnel und DNS sind im Free-Plan enthalten, nur das
   "partial/CNAME setup" ohne Nameserver-Wechsel wäre Business-only, siehe Schritt 2).
4. Cloudflare scannt bestehende DNS-Einträge der Domain und schlägt zwei Nameserver vor (z. B.
   `xxx.ns.cloudflare.com`, `yyy.ns.cloudflare.com`) - **notieren**, die werden in Schritt 2 gebraucht.

## 2. Nameserver bei all-inkl auf Cloudflare umstellen

**Das ist der eigentliche Knackpunkt** - erst danach kann der Tunnel überhaupt einen Hostnamen
veröffentlichen.

1. Bei all-inkl (KAS-Verwaltung) einloggen → *Domains* → `datametric360.de` → Nameserver-Einstellungen.
2. Von all-inkls eigenen Nameservern auf die beiden von Cloudflare vorgeschlagenen (Schritt 1.4)
   umstellen - das ist ein **"Full setup"**: die komplette DNS-Verwaltung der Domain wandert zu
   Cloudflare, nicht nur ein einzelner Eintrag. Das ist hier folgenlos, weil auf dieser Domain nichts
   anderes liegt (keine Webseite, kein Postfach) - siehe die Einschränkung in
   `../COMPANION_APP_ARCHITECTURE.md` §5 Punkt 4, warum die Domain extra dafür angelegt wurde.
3. Umstellung kann laut Cloudflare bis zu 24 Stunden dauern (meist deutlich schneller). Status im
   Cloudflare-Dashboard prüfen - die Domain wechselt dort von "Pending Nameserver Update" auf "Active".
4. Erst wenn "Active" angezeigt wird, mit Schritt 3 weitermachen (ein Tunnel-Hostname lässt sich vorher
   zwar anlegen, aber die DNS-Auflösung funktioniert erst danach).

## 3. Cloudflared-Add-on installieren und Tunnel einrichten

1. In Home Assistant: *Einstellungen → Add-ons → Add-on Store* → nach "Cloudflared" suchen, installieren.
   Empfohlen und geprüft: [`homeassistant-apps/app-cloudflared`](https://github.com/homeassistant-apps/app-cloudflared)
   (Tobias Brenner, MIT-lizenziert, aktiv gepflegt, >1.500 GitHub-Stars) - kein offizielles
   Home-Assistant-Add-on, aber das etablierte Community-Add-on für genau diesen Zweck; nicht die
   eigenständige `cloudflared`-CLI von Hand einrichten.
2. Im Cloudflare-Dashboard: *Zero Trust → Networks → Tunnels* → *Create a tunnel* → Typ "Cloudflared" →
   Namen vergeben (z. B. `datametric360`).
3. Cloudflare zeigt einen Tunnel-Token an - diesen im HA-Add-on unter *Konfiguration* im Feld
   **`tunnel_token`** eintragen ("Remote Tunnel Setup" in den Add-on-Docs; alle anderen
   Konfigurationsfelder des Add-ons werden dann ignoriert). Kein manueller `cloudflared`-Aufruf per SSH
   nötig, **und kein Cloudflare-API-Token nötig** - das Add-on hat neben diesem Weg auch einen zweiten,
   browserbasierten Modus ("Local Tunnel Setup", legt den Tunnel selbst per Login-Link an), der hier
   bewusst nicht verwendet wird: der manuelle Weg über den Tunnel-Token macht sichtbar und
   nachvollziehbar, welcher Tunnel mit welchem Namen existiert, statt das dem Add-on zu überlassen.
4. Add-on starten. Im Cloudflare-Dashboard sollte der Tunnel danach als "Healthy"/verbunden angezeigt
   werden - das bestätigt die **ausgehende** Verbindung vom HAOS-Host zu Cloudflares Edge (kein
   Router-Port nötig, kein Port-Forward einzurichten).
5. **Öffentlichen Hostnamen noch nicht auf Home Assistant selbst zeigen lassen** - das kommt erst in
   Schritt 5, nachdem der Reverse Proxy (Schritt 4) steht. Der Tunnel zeigt am Ende auf den Reverse
   Proxy, nie direkt auf Port 8123.

## 4. Nginx Proxy Manager installieren und Pfad-Freigabeliste eintragen

1. *Einstellungen → Add-ons → Add-on Store* → "Nginx Proxy Manager" installieren, starten.
2. Die Weboberfläche des Add-ons öffnen (Standard-Login beim ersten Start: `admin@example.com` /
   `changeme` - **sofort ändern**, siehe Add-on-Dokumentation).
3. *Hosts → Proxy Hosts → Add Proxy Host*:
   - **Domain Names:** `datametric360.de`
   - **Forward Hostname/IP:** `homeassistant` (interner Name im Supervisor-Docker-Netz;
     alternativ `localhost`/`homeassistant.local.hass.io`, je nach Add-on-Version - im Zweifel im
     Add-on-Log nachsehen, mit welchem Namen sich `homeassistant:8123` von dort aus auflösen lässt)
   - **Forward Port:** `8123`
   - **SSL:** eigenes Cloudflare-Zertifikat reicht (der Tunnel terminiert TLS bereits an Cloudflares
     Edge) - hier kann "Force SSL" aktiv bleiben, ein eigenes Let's-Encrypt-Zertifikat ist nicht
     zwingend nötig, schadet aber auch nicht.
4. Im Tab **Advanced** den kompletten `nginx`-Codeblock aus [`REVERSE_PROXY.md`](REVERSE_PROXY.md)
   (Abschnitt "Nginx Proxy Manager") **unverändert** einfügen - das ist die eigentliche
   Pfad-Freigabeliste: nur `/api/`, `/api/states/sensor.audi_dashboard_*`,
   `/api/services/audi_dashboard/*`, `/api/services/homeassistant/restart`, `/api/websocket`,
   `/audi_dashboard_static/app/*` und `/local/bilder/*.{webp,png,jpg,svg}` kommen durch - alles andere
   (`/lovelace`, `/config`, `/auth/*`, die HA-Oberfläche selbst) liefert `404`.
5. Speichern.

## 5. Cloudflare-Tunnel auf den Reverse Proxy zeigen lassen

1. Zurück im Cloudflare-Dashboard: *Zero Trust → Networks → Tunnels* → den Tunnel aus Schritt 3 öffnen →
   *Public Hostname* → *Add a public hostname*.
2. **Subdomain:** leer lassen (Apex-Domain `datametric360.de` selbst - kein Subdomain-Präfix, siehe
   "Ein einziger Hostname genügt" in `REVERSE_PROXY.md`).
3. **Domain:** `datametric360.de`
4. **Service Type:** `HTTPS` (nicht `HTTP` - Nginx Proxy Manager terminiert selbst wieder TLS).
5. **URL:** die interne Adresse des Nginx-Proxy-Manager-Add-ons, üblicherweise der Add-on-Hostname im
   Supervisor-Netz plus dessen konfigurierten Port (im Add-on selbst unter *Info* nachsehen, welcher
   interne Port/Hostname das ist - **nicht** Port 8123, das wäre HA direkt).
6. Speichern. **Danach unbedingt gegenprüfen, welche URL hier tatsächlich hinterlegt ist** - zeigt sie
   aus Versehen auf `homeassistant:8123` statt auf den NPM-Port, läuft die komplette HA-Oberfläche
   samt Login öffentlich, ohne dass die Pfad-Freigabeliste aus Schritt 4 überhaupt greift. Das ist der
   größte praktische Stolperstein dieser ganzen Einrichtung.

## 6. Sicherheitseinstellungen (Cloudflare + Nginx Proxy Manager)

Zusätzlich zur reinen Pfad-Freigabeliste (Schritt 4) - die eigentliche Sicherheit hängt an genau zwei
Dingen: dem Zugriffstoken und daran, dass wirklich nur die gelisteten Pfade durchkommen. Alles hier ist
zusätzliche Härtung, kein Ersatz dafür.

**Cloudflare, Tab *DNS*:**
- Prüfen, ob beim Domain-Import aus dem alten all-inkl-Bestand zusätzliche DNS-Einträge übernommen
  wurden (z. B. eine Parkseiten-A-Eintragung) - außer dem vom Tunnel selbst angelegten Eintrag soll
  nichts auf der Domain liegen.
- Der vom Tunnel angelegte Eintrag muss **"Proxied"** (orange Wolke) sein, nicht "DNS only" (grau).

**Cloudflare, Tab *SSL/TLS*:**
- Verschlüsselungsmodus **"Full"**, nicht "Flexible".
- **"Always Use HTTPS"** aktivieren.
- Unter *Edge Certificates*: **HSTS aktivieren** (moderate `max-age`, z. B. 6 Monate) - gleicht aus,
  dass `.de` (anders als das ursprünglich erwogene `.app`) nicht auf der HSTS-Preload-Liste steht,
  siehe `COMPANION_APP_ARCHITECTURE.md` §5 Punkt 4.

**Cloudflare, Tab *Security*:**
- **Bot Fight Mode NICHT aktivieren** - die native App ist kein Browser und würde von den
  Bot-Heuristiken vermutlich mitblockiert.
- Optional: eine Rate-Limiting-Regel auf `/api/*` (im Free-Plan in Grenzen enthalten) bremst reines
  Durchprobieren, ersetzt aber nicht den Token.

**Nginx Proxy Manager, Proxy Host:**
- **"Block Common Exploits"** und **"Websockets Support"** aktivieren. **"Force SSL"** braucht ihr nur,
  wenn ihr dem Host ein eigenes Zertifikat gebt - bei "HTTP Only" (siehe SSL-Abschnitt oben, kein
  eigenes Zertifikat nötig, da Cloudflare die Verschlüsselung nach außen übernimmt) ist die Option
  ohnehin ausgegraut.
- ⚠️ **Echter, live gefundener Fehler (2026-08-28) - `include conf.d/include/proxy.conf;` NICHT
  verwenden.** Der Codeblock in `REVERSE_PROXY.md` enthielt ursprünglich diese Zeile in jedem
  `location`-Block (Standard-Praxis bei der vanilla jc21-nginx-proxy-manager-Doku). Beim
  `homeassistant-apps/app-cloudflared`-Gegenstück - genauer: bei diesem NPM-Add-on
  (`homeassistant-apps`, Frenck) - enthält diese geteilte Datei selbst bereits ein `proxy_pass`,
  zusammen mit dem eigenen `proxy_pass` im Block ergibt das `nginx: [emerg] "proxy_pass" directive is
  duplicate` - die Konfiguration lädt dann gar nicht mehr (nginx startet nicht, das Add-on
  crash-loopt). Symptom, falls das passiert: **alle** Pfade liefern "Not Found", auch die, die
  eigentlich erlaubt sein sollten, und das Protokoll zeigt diese `[emerg]`-Zeile beim Start. Ein
  einfacher Neustart des Add-ons behebt das NICHT (die Datei bleibt kaputt) - nötig war eine komplette
  Deinstallation + Neuinstallation des Add-ons. Der aktuelle, korrigierte Codeblock in
  `REVERSE_PROXY.md` verzichtet deshalb auf die `include`-Zeile und schreibt die nötigen
  `proxy_set_header`-Zeilen direkt in jeden Block.

**Zugriffstoken:**
- **Pro Gerät ein eigener Token**, nicht denselben auf mehreren Handys - dann lässt sich ein verlorenes
  Gerät gezielt aussperren (*Profil → Sicherheit → Zugriffstoken*), ohne das andere neu einzurichten.
- Ausschließlich als `Authorization: Bearer`-Header, nie in der URL/Query-String.

**Router:**
- Sicherstellen, dass **kein Port-Forward auf 8123** existiert (auch keiner mehr aus früheren
  Versuchen anderer Ports/Zwecke).

## 7. Prüfen

Von einem Netz **ohne** VPN/Tailscale (z. B. Mobilfunk, WLAN-Tethering vom Handy) die Prüfbefehle aus
[`REVERSE_PROXY.md`](REVERSE_PROXY.md) (Abschnitt "Nach der Einrichtung prüfen") ausführen. Kurzfassung:
`GET /api/` und `GET /api/states/sensor.audi_dashboard_profil` (mit gültigem Zugriffstoken) müssen
funktionieren; `GET /auth/authorize` und `GET /api/config` müssen `404`/`403` liefern; ohne Token muss
`/api/states/...` mit `401` statt `200` antworten. **Und:** Port 8123 darf von außen gar nicht antworten
(z. B. über einen externen Port-Checker prüfen, oder `curl` gegen `http://<öffentliche-WAN-IP>:8123`,
das muss ins Leere laufen).

## 8. Server-Adresse in der App eintragen

Auf jedem Gerät, auf dem die companion-app sideload-installiert ist: beim (erneuten) Einrichten
`https://datametric360.de` als Server-Adresse eintragen, den bestehenden Zugriffstoken wiederverwenden
oder einen neuen erzeugen. Ab hier funktionieren sowohl die normalen Datenabrufe als auch
Fern-OTA-Updates (`AGENTS.md`, Abschnitt zu `@capgo/capacitor-updater`) über denselben Weg - lokal im
Heimnetz weiterhin genauso wie zuvor, da HA selbst unverändert nur lokal erreichbar bleibt und die App
ohnehin dieselbe Server-Adresse für beide Fälle verwendet.

## Was danach noch offen bleibt

- Ein Fehlschlag in Schritt 7 zuerst hier prüfen, in dieser Reihenfolge: Ist die Domain in Cloudflare
  "Active" (Schritt 2)? Zeigt der Tunnel "Healthy" (Schritt 3.4)? Antwortet der Nginx-Proxy-Manager-Host
  lokal überhaupt (`curl` von der HA-Konsole gegen die in Schritt 5.5 eingetragene interne Adresse)?
  Erst danach die Pfad-Regeln selbst (Schritt 4) noch einmal gegen `REVERSE_PROXY.md` vergleichen.
- Ein Gerät verlieren/kompromittiert vermuten: den betroffenen Zugriffstoken im HA-Profil zurückziehen
  (*Profil → Sicherheit → Zugriffstoken (Long-Lived Access Tokens)*) - das sperrt sofort aus, unabhängig
  vom Tunnel/Reverse-Proxy.
- Diese Anleitung deckt nur den Netzwerkweg ab. Für alles rund um Xcode-Signierung/Sideload der App
  selbst: `../COMPANION_APP_ARCHITECTURE.md` §1 ("Distribution: sideload only").