The tree carried uncommitted work from several areas (web push, mobile screens, admin charts, test-hygiene cleanup, CI and map docs). It is landed as one commit so the release pipeline can start from a clean tree; the desktop transcript-correction behaviour shipped in the previous commit and is unchanged here.
135 lines
12 KiB
Markdown
135 lines
12 KiB
Markdown
# Push transport without Firebase — analysis
|
||
|
||
> Status: decision note (2026-09-13; implementation status updated 2026-11-04)
|
||
> Scope: `send-push` Edge Function, `server/supabase/migrations` push outbox, web/mobile notification clients
|
||
> Question: we already pay for Supabase. Can it replace Firebase for notifications?
|
||
|
||
---
|
||
|
||
## 0. TL;DR
|
||
|
||
- **Supabase already is the push backend.** Tokens, devices, durable outbox, leases, retries, and delivery audit all live in Supabase (`push_tokens`, `devices`, `push_deliveries`, `push_dispatch_attempts`, `send-push`). Firebase is only the **last hop** to the device.
|
||
- **Web and iOS are Firebase-free in source.** Web Push (VAPID + RFC 8291 aes128gcm) and Apple APNs (`.p8` token) transports are implemented in `send-push`; the web sidebar and mobile client contain provider-specific registration paths. This does not prove production delivery: matching provider secrets, a deployed drain, authenticated browser/device permission, and real receipt are still open gates.
|
||
- **Android cannot drop Firebase without changing transport.** Google Play Services only delivers push through FCM, and the FCM registration token is minted by the Firebase Messaging SDK, which requires `google-services.json` (a Firebase project). Supabase cannot substitute for that hop.
|
||
- **The scheduled drain was missing and is now added.** Nothing in the repo triggered `send-push?mode=drain`, so transactionally enqueued notifications never left the outbox. A Cloudflare Cron Trigger now drains it every minute.
|
||
- **Firebase-free Android is possible but is a different product decision:** UnifiedPush + a self-hosted distributor (e.g. ntfy). Third-party push services (OneSignal, Pusher) do **not** remove the Firebase dependency; they wrap FCM.
|
||
|
||
---
|
||
|
||
## 1. What exists today
|
||
|
||
| Layer | Owned by | Notes |
|
||
|---|---|---|
|
||
| Token + device registry | Supabase | `push_tokens`, `devices`; writes via `register_push_registration` RPC; RLS denies direct access |
|
||
| Durable outbox + retry/lease | Supabase | `push_deliveries`, `push_dispatch_attempts`, `claim_due_push_dispatches`, `finalize_push_delivery` |
|
||
| Dispatch orchestration | Supabase Edge `send-push` | Auth, event resolution, batching, stale-token handling |
|
||
| **Transports** | **FCM / Web Push / APNs** | `_shared/push-contract.ts`, `_shared/webpush.ts`, `_shared/apns.ts`; all route through `send-push` |
|
||
| Android client | Firebase Messaging SDK | `com.google.firebase:firebase-messaging`, `D3ROFirebaseMessagingService`, `google-services.json`; `FIREBASE_CONFIGURED` build flag |
|
||
| Web client | Browser Push API | `/app/sw.js`; sidebar opt-in/out binds a stable active web device to the `webpush` registration through RPCs |
|
||
| iOS client | Native APNs bridge | Mobile registration chooses `provider: 'apns'` on iOS and unregisters through the shared RPC |
|
||
|
||
So: the only Firebase-specific pieces are (a) the FCM HTTP v1 send + service account, and (b) the Android client token source.
|
||
|
||
---
|
||
|
||
## 2. Platform-by-platform answer
|
||
|
||
### Desktop — no change needed
|
||
In-app events use IPC/EventEmitter and Supabase Realtime. No push transport, no Firebase.
|
||
|
||
### Web — Firebase-free, implemented in source
|
||
- Standard **Web Push** with **VAPID** keys. The browser Push API + service worker handles delivery; the server signs with a VAPID private key and POSTs to the subscription endpoint.
|
||
- The sidebar requests permission from an explicit user gesture, creates/checks in a stable active `platform='web'` device, and stores the serialized subscription in `push_tokens` through `register_push_registration`. Opt-out records a per-user disabled intent before bounded parallel server/local cleanup; an existing local subscription is re-registered through the server RPC before the UI may call it connected. Logout starts cleanup without waiting and always proceeds to sign-out.
|
||
- `NEXT_PUBLIC_VAPID_PUBLIC_KEY` is baked into the browser bundle and must match the Edge Function's `WEBPUSH_VAPID_PUBLIC_KEY`; a missing browser key leaves the control unavailable.
|
||
- No Firebase, no Google account. APNs not involved.
|
||
|
||
### iOS — Firebase-free, implemented in source
|
||
- **APNs** directly: `.p8` key + Key ID + Team ID → JWT (ES256) → `https://api.push.apple.com/3/device/<token>`.
|
||
- Needs an Apple Developer membership (already needed for App Store), **not** a Firebase project.
|
||
- Supabase Edge Function can hold the `.p8` as a secret and sign the JWT with WebCrypto.
|
||
- The mobile notification service chooses `provider: 'apns'` for iOS. A signed-device run with real APNs credentials and receipt is still required.
|
||
|
||
### Android — Firebase-free only via UnifiedPush
|
||
- Google Play Services delivers notifications through FCM. The official `FirebaseMessaging` SDK mints the registration token, and it requires `google-services.json`. There is no supported way to obtain an FCM token without a Firebase project.
|
||
- FCM HTTP v1 also requires an OAuth2 service account with the `firebase.messaging` scope, which means an FCM-enabled Google Cloud/Firebase project (the Firebase *console* is not strictly required, but the project is).
|
||
- Firebase-free options:
|
||
1. **UnifiedPush + self-hosted distributor (ntfy)** — open standard; the app registers with a distributor (`ntfy`, NextPush) which holds a persistent connection; the server POSTs to the distributor. No Google. Requires the user to have a distributor installed (or the app to bundle one) and adds a background-connection battery cost.
|
||
2. **Own persistent WebSocket / foreground service** — free of Google but unreliable: Android Doze/App Standby kills sockets, so notifications cannot wake a killed app. Acceptable only for in-app live updates while running.
|
||
3. **Third-party (OneSignal, Pusher Beams, Expo Push)** — still FCM/APNs underneath. Does not remove Firebase for Android.
|
||
|
||
---
|
||
|
||
## 3. What "Firebase" actually costs us today
|
||
|
||
- A Firebase project + `google-services.json` committed for the Android build (build blocks release if missing).
|
||
- A service account JSON in Supabase secrets (`FCM_SERVICE_ACCOUNT_JSON`) and `FCM_PROJECT_ID`.
|
||
- No Firebase database/auth/storage/analytics is used. It is a push-only dependency.
|
||
|
||
If the goal is "no Firebase at all", the decision reduces to: replace Android transport (UnifiedPush) or accept FCM on Android only.
|
||
|
||
---
|
||
|
||
## 4. Recommended path
|
||
|
||
1. **Keep Supabase as the SSOT/outbox** (already true). Do not move token/outbox logic.
|
||
2. **[done] Implement `webpush` + `apns` transports** in `send-push` (`_shared/webpush.ts`, `_shared/apns.ts`).
|
||
3. **[source done] Register web/APNs clients through the device-bound RPCs.** Keep provider configuration and real delivery as runtime gates.
|
||
4. **For Android, offer two modes behind config:**
|
||
- `fcm` (default): minimal Firebase project, push-only usage.
|
||
- `unifiedpush` (opt-in): self-hosted ntfy distributor; documented UX and battery caveats.
|
||
5. **Do not adopt OneSignal/Pusher** as a "Firebase replacement" — it does not remove the dependency.
|
||
|
||
### Effort sketch
|
||
| Item | Effort | Risk |
|
||
|---|---|---|
|
||
| Web Push (VAPID) transport + tests | S–M | low — **done** |
|
||
| Web browser device/subscription flow | M | medium — **source + contract tests done**, live configuration/delivery pending |
|
||
| APNs (JWT ES256 `.p8`) transport + client registration | M | medium — **source + unit tests done**, Apple key/live delivery pending |
|
||
| Cloudflare cron drain | S | low — **done** |
|
||
| UnifiedPush Android (client lib + distributor + server transport) | L | high (UX, battery, distributor dependency) |
|
||
| Minimal Firebase project for Android FCM | S (external action) | low |
|
||
|
||
---
|
||
|
||
## 5. Implemented (2026-09-13; client update 2026-11-04)
|
||
|
||
| Piece | Where | Notes |
|
||
|---|---|---|
|
||
| Web Push transport | `_shared/webpush.ts` | VAPID ES256 JWT + RFC 8291 `aes128gcm` encryption; strict config/subscription validation; 200/404/410/413 mapping |
|
||
| APNs transport | `_shared/apns.ts` | Token-based `.p8` ES256 JWT (cached ~50 min); production/sandbox hosts; stale (`BadDeviceToken`/`Unregistered`) and 403 handling |
|
||
| Provider routing | `send-push/index.ts` | `fcm` / `webpush` / `apns` dispatched with per-delivery stale → `stale`, payload → `permanent_failure`, else retryable; unknown providers stay `push_provider_not_supported` |
|
||
| Cloudflare cron drain | `server/cloudflare-worker/src/push-drain.ts` + `scheduled()` + `wrangler.toml [triggers] crons` | POSTs `send-push?mode=drain&limit=…` with the service-role bearer every minute |
|
||
| Tests | `_shared/webpush.test.ts`, `_shared/apns.test.ts`, `push-drain.test.ts`, `push-contract.test.ts` | 10 new tests incl. an RFC 8291 decrypt round-trip; CI runs the edge suite and the worker drain test |
|
||
| Web client | `apps/web/public/sw.js`, `src/lib/{web-device,web-push,web-push-session}.ts`, `web-push-control.tsx` | Explicit opt-in/out, stable active device, device-bound RPCs, persistence rollback, disabled-intent reconciliation, bounded parallel cleanup, non-blocking logout; standalone image copies the service worker |
|
||
| Web contract tests | `apps/web/e2e/web-push.spec.ts` | 17 tests for installation identity, revoked-device refusal, permission/VAPID gate, register/unregister RPCs, rollback, stale-subscription reconciliation, bounded cleanup, and logout independence |
|
||
| iOS client registration | `apps/mobile-rn/src/features/notifications/*` | Platform-aware APNs/FCM registration and unregister path; unit-tested, not live-delivery verified |
|
||
|
||
### Local runtime evidence (2026-11-04)
|
||
|
||
An ephemeral VAPID pair, throwaway user, isolated Supabase project, and throwaway Chrome profile proved browser opt-in, one active web device, one device-bound `webpush` token, one pending dispatch, a completed local drain, and a `push_deliveries.status='delivered'` result. That last state means the Web Push endpoint accepted the request; it does **not** prove that the service worker displayed or received a notification. No browser receipt was observed. A later production-standalone attempt built and served successfully but timed out during throwaway login navigation before the dashboard, so production-rendered desktop/mobile accessibility, permission/subscription, and receipt remain explicit gates. All ephemeral keys, rows, user data, and the browser profile were removed; the isolated stack was restored without VAPID configuration and then deleted.
|
||
|
||
### Required configuration
|
||
| Secret / var | Consumer | Purpose |
|
||
|---|---|---|
|
||
| `WEBPUSH_VAPID_PUBLIC_KEY` / `WEBPUSH_VAPID_PRIVATE_KEY` / `WEBPUSH_SUBJECT` | Supabase Edge Function | VAPID signing; subject must be `mailto:` or `https:` |
|
||
| `NEXT_PUBLIC_VAPID_PUBLIC_KEY` | Web image build | Public half of the same VAPID pair, baked into the client bundle; missing means unavailable/fail-closed |
|
||
| `APNS_KEY_ID` / `APNS_TEAM_ID` / `APNS_PRIVATE_KEY` / `APNS_TOPIC` / `APNS_ENVIRONMENT` | Supabase Edge Function | APNs token auth; topic is the bundle id (`com.d3ro.voice`) |
|
||
| `SUPABASE_URL` / `SUPABASE_SERVICE_ROLE_KEY` / `PUSH_DRAIN_BATCH_LIMIT` | Cloudflare Worker | Cron drain target + auth (service role key as `wrangler secret`) |
|
||
|
||
### Remaining work
|
||
- **Runtime proof:** configure matching web/server VAPID values and APNs credentials, build/deploy the web image and Edge/cron code, then prove authenticated browser/iOS registration, outbox drain, and real receipt. Source and automated contract tests alone do not satisfy this gate.
|
||
- **Android decision:** keep FCM or adopt UnifiedPush (see §2/§3).
|
||
|
||
---
|
||
|
||
## 6. Related
|
||
|
||
- `server/supabase/functions/_shared/push-contract.ts` — FCM transport + provider types
|
||
- `server/supabase/functions/_shared/webpush.ts` — Web Push (VAPID + RFC 8291)
|
||
- `server/supabase/functions/_shared/apns.ts` — APNs (.p8 token)
|
||
- `server/supabase/functions/send-push/index.ts` — dispatch orchestration
|
||
- `server/cloudflare-worker/src/push-drain.ts` — cron drain
|
||
- `apps/web/src/lib/web-push-session.ts` + `apps/web/src/components/layout/web-push-control.tsx` — browser device/subscription orchestration
|
||
- `apps/mobile-rn/src/features/notifications/*` — client token/provider contract
|
||
- `docs/map/11-gap-backlog.md` `GAP-PUSH-01` / `GAP-PUSH-02` / `EXT-FIREBASE-01`
|
||
- `docs/v3/MOBILE_APP_COMPLETION_SSOT.md` `EXT-011`
|