# Firebase

Das Firebase-Projekt heißt **MetalCircle**. Android ist dauerhaft als `de.pinguholic.concerts` registriert. Manuelle Testnachrichten funktionieren bereits. Automatischer Versand für Freundschaftsanfragen, Direktnachrichten und Veranstaltungseinladungen ist implementiert und benötigt einen separaten serverseitigen Zugang sowie `PUSH_ENABLED=true`.

## Unterschiedliche Konfigurationsdateien

- `android/android/app/google-services.json`: lokale, Git-ignorierte Android-Client-Konfiguration. Projekt-/App-Kennungen und der Client-API-Key werden vom Build in die APK übernommen; sie sind kein Backend-Privatschlüssel.
- **Service-Account-JSON**: privater Schlüssel für das Backend. Niemals in Git, APK, Docker-Image, Webassets, Chat, Wiki oder Logs aufnehmen. Die Android-Datei ersetzt diesen Zugang nicht.

## Lokale Entwicklungs-/Testumgebung

1. In Firebase **MetalCircle** auswählen und die tatsächliche **Projekt-ID** notieren; sie kann vom Anzeigenamen abweichen.
2. In der zugehörigen Google Cloud Console die **Firebase Cloud Messaging API (HTTP v1)** prüfen/aktivieren.
3. Der lokale Test verwendet den dedizierten Service Account `metalcircle-push-local@metalcircle-30d9b.iam.gserviceaccount.com`. Für dessen Versand ist die Projektrolle **Firebase Cloud Messaging API Admin**, Rollen-ID `roles/firebasecloudmessaging.admin`, erforderlich. Diese genaue Rolle ist diesem lokalen Test-Service-Account auf Projektebene im Projekt `metalcircle-30d9b` zugewiesen. Sie enthält `cloudmessaging.messages.create`. Nicht mit ähnlich benannten Firebase-Administrationsrollen verwechseln; OAuth-Tokenbezug allein beweist keine Versandberechtigung. Keine persönlichen oder Gitea-Zugänge verwenden. Siehe [Firebase IAM](https://firebase.google.com/docs/projects/iam/permissions) und [FCM-Rollen](https://docs.cloud.google.com/iam/docs/roles-permissions/firebasecloudmessaging).
4. Den privaten JSON-Schlüssel geschützt **außerhalb des Repositories und Docker-Buildkontexts** speichern. Der Betreiber verwaltet die Datei. [Firebase Admin Setup](https://firebase.google.com/docs/admin/setup) beschreibt Service-Account-Dateien.
5. Dateirechte einschränken, beispielsweise `chmod 600 /absoluter/pfad/firebase-service-account.json`. Keine Inhalte ausgeben.
6. In der lokalen `.env` die folgenden Werte selbst eintragen:

```dotenv
PUSH_ENABLED=true
FIREBASE_PROJECT_ID=<tatsaechliche-test-projekt-id>
FIREBASE_SERVICE_ACCOUNT_FILE=/absoluter/pfad/firebase-service-account.json
```

7. In der eigenen lokalen HTTP-Testumgebung starten:

```bash
COOKIE_SECURE=false docker compose -f compose.yml -f compose.push.yml up -d --build web
```

`compose.push.yml` liest `FIREBASE_SERVICE_ACCOUNT_FILE` als absoluten Host-Pfad, bindet diese Datei **read-only** unter `/run/secrets/firebase-service-account.json` in den `web`-Container ein und setzt `GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/firebase-service-account.json`. Die Quelldatei muss existieren. Der Sender prüft, dass `FIREBASE_PROJECT_ID` zur Projekt-ID des Credentials passt. Die Android-App muss dasselbe Firebase-Projekt verwenden. Schlüsseldatei, `.env` und Token gehören weder ins Repository noch in ein Image.

Cloud-Staging richtet der Betreiber separat ein; dort hinter HTTPS `COOKIE_SECURE=true` lassen. Codex auf PinguCore greift nicht automatisch darauf zu. Produktion bekommt später eigene Credentials, keine kopierten Testschlüssel.

## Verifizierter lokaler E2E-Stand

Am **15.09.2026** wurde der vollständige lokale Weg mit dem Android-Testgerät und dem lokalen Backend erfolgreich geprüft. Nach Zuweisung von `roles/firebasecloudmessaging.admin` verschwand der vorherige HTTP-403-Fehler `PERMISSION_DENIED`. Das Service-Account-Credential stimmte mit `FIREBASE_PROJECT_ID=metalcircle-30d9b` überein; der Firebase Admin SDK Versand wurde vom FCM HTTP-v1-Endpunkt angenommen.

Freundschaftsanfrage und Veranstaltungseinladung wurden im Android Notification Manager nachgewiesen. Die Direktnachrichten-Benachrichtigung wurde auf dem Gerät gesehen; Antippen öffnete den zugehörigen Chat. Alle drei Benachrichtigungen verwenden generische Vorschautexte ohne Nachrichtentext oder private Veranstaltungsdetails. Die installierte Test-App war `1.1.0-debug`, Package ID `de.pinguholic.concerts`.

Für eine Wiederholung lokale App und Backend verwenden; mit `adb reverse tcp:8080 tcp:8080` wird der Android-Testbuild an den lokalen Port 8080 weitergeleitet. Keine Cloud-Staging- oder Produktionsumgebung verwenden. In der Datenbank bedeutet `push_notifications.state='sent'`, dass der Firebase-Sendeaufruf angenommen wurde; für einen vollständigen E2E-PASS zusätzlich den tatsächlichen Android-Empfang über Notification Manager oder gleichwertige Gerätebeobachtung prüfen.

Automatisierte Backend-Tests simulieren Firebase und belegen nicht die Cloud-IAM-Berechtigung. Die lokale Suite mit 53 Tests und der Android-Debug-Build waren erfolgreich; der oben beschriebene Gerätetest hat zusätzlich den echten FCM-Versand und Empfang bestätigt. Bei erneutem `configuration`-/403-Fehler Projekt-ID, aktiven Service Account, dessen `roles/firebasecloudmessaging.admin`-Zuweisung im richtigen Firebase-Projekt, API-Aktivierung und Secret-Mount prüfen. Logs enthalten absichtlich keine vollständigen Firebase-Fehlerantworten oder Secrets. Keine Legacy-Server-Keys einsetzen.