d3ro-voice/docs/deployment/push-transport-without-firebase.md
Yun Chan 7fe49c437e chore: land in-progress workspace changes before 1.16.2
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.
2026-11-05 21:58:44 +09:00

135 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`