Default push backend to ntfy; FCM opt-in with privacy warning (issue #10)
CI / Gateway plugin tests (push) Successful in 5m3s
CI / Kotlin tests (android host + desktop) (push) Successful in 7m6s

- IRIS_PUSH_BACKEND now defaults to ntfy (keeps push metadata on your own
  infrastructure); FCM is opt-in via IRIS_PUSH_BACKEND=fcm
- build_push_backend(): ntfy for empty/unknown names, FCM only on explicit 'fcm'
- gateway setup: warn when FCM is chosen (metadata routed via Google's servers)
- README: privacy note + dedicated push section; new docs/playstore-listing.md
  with the FCM/ntfy privacy note for the Play Store listing
- docs: 00/02/03/08/12/16 + setup.md updated to ntfy-default wording
- tests: default-backend assertion updated (86/86 pass)
This commit is contained in:
ARIA committed 2026-08-24 19:04:40 +02:00
1 parent 70282dfb65
commit 746d809d48
14 files changed
+136 -56

No files matched your search

+23 -19
View File
@@ -39,7 +39,8 @@ What it does:
- Generates `IRIS_TOKEN` (64 hex chars) if none exists and stores it in
`~/.hermes/.env` (it prints the token once, at generation).
- Prompts for the WS bind host (default `127.0.0.1`), port (default `8790`),
and push backend (`fcm` or `ntfy`, default `fcm`).
and push backend (`ntfy` or `fcm`, default `ntfy`); warns when `fcm` is
chosen (push metadata via Google's servers).
- Prints the pairing payload (a QR-encodable `iris://pair?host=…&port=…&token=…`
string), a scannable QR of that payload, and the server URL
(`ws://<host>:8790/ws`).
@@ -100,26 +101,10 @@ Push wakes a backgrounded/offline device; on reconnect the app syncs the
outbox, so nothing is lost. Push fires when the device is offline, plus for
high-priority events (approvals, clarifies, cron) even when a device is live.
### FCM (default; needs a Firebase project)
1. Create a Firebase project (console.firebase.google.com) and add an Android
app with the app's applicationId; download `google-services.json` into
`app/androidApp/`.
2. Create a service account (Project settings → Service accounts → Generate new
private key) and store the JSON path in `~/.hermes/.env`:
`IRIS_FCM_SERVICE_ACCOUNT=/path/to/service-account.json`.
3. Keep `IRIS_PUSH_BACKEND=fcm` (the default).
Without a Firebase project the FCM path is **inert** (the app's FCM service
does nothing) — use ntfy below, or add Firebase later.
**What you see:** system notifications for new messages when the app is
backgrounded; tapping one deep-links to the chat.
### ntfy (zero-config fallback)
### ntfy (default; zero-config)
```
IRIS_PUSH_BACKEND=ntfy
IRIS_PUSH_BACKEND=ntfy # the default — can be left unset
```
- The device **generates its own topic** automatically (no `NTFY_TOPIC` needed);
@@ -128,10 +113,29 @@ IRIS_PUSH_BACKEND=ntfy
recommended** — the public ntfy.sh SSE endpoint is flaky (it has served its
web UI instead of the stream), while a self-hosted instance gives reliable
SSE. For a real trust boundary use a private topic + `NTFY_AUTH_TOKEN`.
- **Privacy:** ntfy keeps push metadata (title, topic) on your own
infrastructure — this is the backend for truly private communication.
**What you see:** a low-priority foreground "ntfy listener" notification while
the app is off; incoming pushes trigger a silent sync.
### FCM (opt-in; needs a Firebase project)
> **Privacy note:** FCM push metadata (notification title, device token) is
> routed through **Google's servers**. If you want truly private
> communication, use ntfy (self-hosted) instead — it is the default.
1. Create a Firebase project (console.firebase.google.com) and add an Android
app with the app's applicationId; download `google-services.json` into
`app/androidApp/`.
2. Create a service account (Project settings → Service accounts → Generate new
private key) and store the JSON path in `~/.hermes/.env`:
`IRIS_FCM_SERVICE_ACCOUNT=/path/to/service-account.json`.
3. Set `IRIS_PUSH_BACKEND=fcm`.
Without a Firebase project the FCM path is **inert** (the app's FCM service
does nothing) — use ntfy (the default), or add Firebase later.
## 5. Remote access
- **Tailscale / WireGuard (recommended):** the gateway gets a stable tailnet IP;