oott/push_notifications.md

# Push notifications via FCM + project-operated relay

Implementation plan for delivering push notifications to OOTT's own iOS and
Android apps, triggered from the backend, as an alternative to Pushover.

Status: **planned, not started.** Development begins after this document is
agreed. No code has been written yet.

## Goal

Deliver notifications (new device, device back online, device changed) to a
user's phone running the OOTT mobile app, even when the app is backgrounded or
closed, on both iOS and Android. This is a new `notifications.method` alongside
the existing `pushover` method — it does not replace Pushover, it sits next to
it.

## Background constraint

To reach a backgrounded/closed app you must go through the OS push gateways:
APNs (iOS) and FCM (Android). There is no way around them. We use **Firebase
Cloud Messaging (FCM HTTP v1)** as a single integration: it delivers to Android
natively and bridges to APNs for iOS (our APNs key is uploaded into Firebase).

Because OOTT ships a single store-distributed app, the Firebase project and APNs
key are **project-owned**, not per-self-hoster. We therefore route sends through
a small **project-operated relay** so we never distribute project secrets to
self-hosters and so self-hosters need zero push credentials of their own.

## Locked decisions

1. **Relay lives in this monorepo**, under a new top-level `relay/` directory.
   It is implemented in **TypeScript** and deployed as a **Firebase Cloud
   Function** (scale-to-zero). The `relay/` dir holds the source; only the
   deploy target differs from an always-on server.
2. **Phase 1 is the shipped feature.** It needs no shared secret: protection
   rests on FCM project scoping + per-IP rate limiting + a billing cap.
   Attestation hardening (Play Integrity / App Attest) is **deferred, optional
   future work** — built only if abuse signals appear (see "Optional future
   hardening"). The architecture leaves room to layer it on without reworking
   Phase 1.
3. **Push is opt-in per device** via a toggle in the app's settings (not
   auto-enabled on permission grant).

## Architecture

```
Flutter app ──register FCM token──► OOTT backend (self-hosted, LAN)
                                         │ stores tokens in its SQLite DB
                                         │
   new-device event ─────────────────────┤
                                         ▼
                              POST /v1/push {[tokens], payload}
                                         ▼
                          OOTT Push Relay (Firebase Cloud Function, stateless)
                            FCM creds never leave Google (runtime SA)
                                         ▼
                                   FCM HTTP v1 (Google)
                                    ├──────────► Android devices
                                    └──► APNs ──► iOS devices
```

Key properties:

- **The relay is stateless** — no database, no accounts, no PII at rest. The
  self-hosted backend already owns SQLite, an API, and a LAN channel to the app,
  so it stores the device tokens. The relay only forwards.
- **FCM credentials never leave Google.** As a Cloud Function, the relay
  authenticates to FCM via its runtime service account through the
  `firebase-admin` SDK — there is no service-account JSON for us to hold, store,
  or rotate. The "keep project secrets off self-hosters" goal becomes "Google
  keeps the secret."
- **"Only our app" is guaranteed by FCM project scoping**: the relay sends
  through our single Firebase project, so tokens belonging to any other app are
  rejected by FCM. No caller can make the relay push to a different app.
- **Minimal payloads**: the relay only ever sees a short title/body plus
  `data: {notification_id, mac}`. Full device detail (MAC/IP/vendor) is fetched
  from the **local** backend when the user taps the notification. This keeps
  network metadata off project servers — privacy and reduced liability. Because
  that tap-through fetch only works when the phone can reach the local backend
  (on-LAN or via the user's own remote access), the title/body must stay
  self-sufficient — the existing event copy already summarizes the event.

## Phase 1 — working end-to-end push

### Component 1: relay service (`relay/`, new)

- **TypeScript Firebase Cloud Function**, stateless. Scales to zero — no idle
  cost, no server/OS to patch, TLS and a stable HTTPS URL provided by the
  platform.
- Endpoints (HTTP function routes):
  - `POST /v1/push` — `{ tokens: [...], notification: {title,
    body}, data: {...} }` → send via the `firebase-admin` SDK
    (`messaging().sendEach(...)`, batched multicast) → return per-token results
    (`ok` / `unregistered` / `invalid`) so the caller can prune dead tokens.
  - `GET /healthz` — liveness.
- FCM client: the `firebase-admin` SDK authenticates via the function's runtime
  service account — **no service-account JSON to manage, no OAuth-token minting
  or caching code**. `sendEach` returns per-token success/error, giving us
  pruning for free.
- **No auth secret in Phase 1.** Protection rests on three layers that depend
  on no shared secret: FCM project scoping (can only reach OOTT installs),
  per-source-IP rate limiting, and the billing cap below. This keeps
  self-hosters at zero configuration and avoids committing a secret to the
  open-source repo. (If drive-by invocation noise ever becomes an issue, a
  non-secret client key can be added later without design changes.)
- **Rate limiting per source IP** (one home/deployment ≈ one public IP) via a
  lightweight Firestore counter, so one abuser cannot starve other users. Use
  generous limits to tolerate the occasional CGNAT-shared IP.
- **Billing cap + budget alert** on the project — the hard ceiling against cost
  runaway, the one risk the per-invocation model adds. Together with rate
  limiting and FCM project scoping, this removes cost as a reason to need
  attestation.
- Config via Cloud Function env: rate-limit params, log level. No secrets
  required in Phase 1.
- Tests: rate limiting, payload validation (reject malformed/oversized
  requests), FCM-response → result mapping (mock the `firebase-admin` messaging
  call).
- Deployment: `firebase deploy` of the function. Cost ~$0 within the free tier
  (see Cost summary).

### Component 2: backend changes (existing Rust service)

- **Migration** `database_migrations/10-add_push_tokens/up.sql`: `push_tokens`
  table — `id`, `token` (unique), `platform` (`android`/`ios`), `created_on`,
  `last_seen` (RFC3339, matching the existing datetime convention). A `voucher`
  column would be added later only if attestation is built (see "Optional future
  hardening").
- `src/db/push_tokens.rs` — `upsert`, `list`, `delete`, `delete_many` (prune
  dead tokens). Unit tests mirroring `db/notifications.rs`.
- `src/model/push_tokens.rs` — `PushToken` + payload structs, deriving
  `ToSchema`.
- `src/web_server/push_tokens.rs` — handlers behind the existing bearer `auth`
  middleware:
  - `PUT /api/push_tokens` — register/refresh `{token, platform}`.
  - `DELETE /api/push_tokens/{token}` — unregister.
  Wired into the router and into `ApiDoc` `paths(...)` + `components(schemas())`
  in `web_server.rs`, plus a new `push_tokens` OpenAPI tag.
- `settings.rs` — support `method = "fcm_relay"` and a `[notifications.fcm_relay]`
  section with a single `relay_url` that **defaults to the project's deployed
  relay**, so enabling push needs only `method = "fcm_relay"` and nothing to
  paste — consistent with "zero push credentials for self-hosters". Add parse
  tests.
- `src/events/fcm_relay.rs` — sender mirroring `pushover.rs`: load tokens from
  DB, POST to relay, prune `unregistered`/`invalid` tokens from the response.
- `src/events.rs` — add an `"fcm_relay"` arm in `send_notification` using the
  minimal-payload design above.
- Tests: sender against a mocked relay endpoint, DB CRUD/prune, settings
  parsing, endpoint API tests. Run `./run_tests.sh` and `./lint.sh`.

### Component 3: Flutter app changes

- Deps: `firebase_core`, `firebase_messaging`, `flutter_local_notifications`.
- Platform config: `google-services.json` (Android), `GoogleService-Info.plist`
  (iOS); iOS Push Notifications + Background Modes capabilities. APNs key lives
  only in the Firebase console.
- `lib/utils/push_service.dart` — init Firebase, request permission, get token,
  register via API, handle token refresh, and handle taps → deep-link to the
  device/notification via `go_router`. The `notification` payload is shown by the
  OS directly when the app is backgrounded/terminated; `flutter_local_notifications`
  is used to display alerts while the app is in the **foreground** (and for
  Android channel configuration).
- `lib/utils/api/oott_api_push.dart` — `registerPushToken` /
  `unregisterPushToken`, following the existing `oott_api` split.
- Settings UI: per-device "Enable push on this device" toggle (calls
  register/unregister, shows permission state). Uses theme colors and
  `UISnackbars` per project rules.
- Tests: push_service logic (mocked messaging), API tests via the Dio-adapter
  mock seam, widget test for the toggle. Run `./run_tests.sh` and
  `dart analyze`.

### One-time project-owned setup (manual, documented, no secrets committed)

- Firebase project + Android/iOS apps registered.
- Apple Developer APNs `.p8` key uploaded into Firebase.
- Cloud Function deployed; its runtime service account grants FCM access (no
  service-account JSON to generate or store).
- Steps captured in `relay/README.md`. Secrets never committed (project rule).

## Optional future hardening (deferred) — attestation

**Not part of the shipped feature.** In the Cloud Function context, Phase 1's
rate limiting + billing cap already cover cost-runaway, and FCM project scoping
already prevents wrong-app targeting. The *only* residual threat attestation
addresses is **spam to harvested genuine OOTT tokens** (an attacker who has
collected real tokens from their own installs or by breaching self-hosted
backend DBs pushing to those specific users). For OOTT's threat profile — a
niche, self-hosted, low-value target with bounded blast radius — that is a
low-probability, low-impact risk, and attestation carries real cost (uneven
Flutter coverage, server-side Play Integrity + App Attest verification, voucher
issuance/refresh/storage, added complexity to an otherwise trivial stateless
function).

**Build this only if a trigger appears:**
- Evidence of token harvesting or relay abuse.
- An actual spam incident through the relay.
- Significant user growth that raises the target's value.

If built, it proves each token came from a genuine instance of our shipped app:

- **Android → Play Integrity API**, **iOS → App Attest (DCAppAttest)**.
- Relay gains `POST /v1/attest`: verify the platform proof + FCM token → return
  a **signed voucher** for that token. Vouchers are **HMAC-signed JWTs** (relay
  both issues and verifies them, so symmetric signing is sufficient — no keypair
  distribution). Voucher carries `{fcm_token_hash, platform, exp}`, short TTL,
  refreshed on token refresh. Relay stays stateless: it just verifies its own
  signature.
- `/v1/push` additionally requires a valid voucher per token.
- Backend: add `voucher` column to `push_tokens`; store and forward it.
- App: obtain attestation, exchange for voucher at registration, send voucher to
  backend.
- New Cloud Function secret: HMAC signing secret.
- Flutter attestation coverage is uneven; evaluate platform-channel vs. a
  maintained package during this phase.

## Cost summary

- FCM messages and APNs: **$0**.
- Apple Developer ($99/yr) and Google Play ($25 one-time): already required for
  the app, not incremental to push.
- **Relay (Cloud Function): ~$0.** Scales to zero, and the free tier (~2M
  invocations/mo) comfortably covers OOTT at realistic scale; only pennies if it
  is ever exceeded. No idle cost, no host, no domain/TLS to buy. A small
  Firestore counter for rate limiting also stays within free tier at this
  volume.
- Real cost is operational: the relay is still a shared dependency and a single
  point of failure for everyone's notifications; budget for monitoring and
  backward-compatible relay API versioning across many deployed backend
  versions. (Cloud Functions removes the OS-patching burden of a VPS.)

## Security / abuse notes

- FCM project scoping bounds the blast radius to OOTT app installs only — no
  caller can target arbitrary people or other apps.
- Phase 1 has no shared secret to leak: defense is FCM project scoping + per-IP
  rate limiting + billing cap. Deferred attestation would add the strong
  "genuine app instance" guarantee if ever needed.
- Token pruning loop (relay reports dead tokens → backend deletes) must be
  implemented end-to-end or tokens accumulate.
- **Push is best-effort.** `send_notification` records the notification in the
  backend DB *before* contacting the relay (as it already does for Pushover), so
  a relay or network failure never loses the event — only that one push. The
  in-app notification list is the durable record; there is deliberately no push
  retry queue in v1.

## Build & verification order

1. Migration + DB layer + model (tests).
2. Backend endpoints + OpenAPI wiring (API tests).
3. Relay Cloud Function Phase 1 (tests) + `firebase deploy`.
4. Backend `fcm_relay` sender + settings (tests against mock relay).
5. Flutter integration + settings toggle (tests).
6. Manual end-to-end on real Android + iOS devices.
7. (Deferred, only if triggered) attestation + vouchers across relay, backend,
   and app.

Each step ends with the relevant `run_tests.sh` / `lint.sh` / `dart analyze`
green before moving to the next, per project rules.