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

12 KiB
Raw Blame History

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.


  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).

  • 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