Browser Push Notifications

AuthProxy provides browser Web Push delivery for background notifications. Web Push is not a polling mechanism and it does not replace Server-Sent Events (SSE).

How Delivery Works

The delivery path is:

Business event
  -> AuthProxy EventPoller
  -> PushDispatcher
  -> WebPushSender
  -> Browser push provider
  -> Browser wakes /sw.js
  -> Service worker shows the notification

The service worker does not fetch notifications from AuthProxy. It is woken by the browser after the browser receives a push message from its vendor push provider.

Browser Push Providers

When a user enables notifications, the browser creates a subscription through PushManager.subscribe(). The subscription contains the provider endpoint.

Browser / OS	Typical endpoint	Notes
Chrome / Edge on Android or desktop	https://fcm.googleapis.com/fcm/send/...	Delivered through Google FCM
Safari / iOS installed PWA	https://web.push.apple.com/...	iOS 16.4+, installed PWA only
Firefox	Mozilla Autopush endpoint	Provider is selected by the browser

AuthProxy sends to the endpoint saved in the browser subscription. It does not choose Google or Apple directly.

Required Setup

A working deployment needs:

1. AuthProxy WebPush.Enabled = true.
2. A VAPID public/private key pair and WebPush.Subject.
3. AuthProxy database table web_push_subscription.
4. PushSending enabled for the active AuthProxy node.
5. One root service worker at /sw.js on the same origin as the PWA.
6. Valid PWA manifest and notification icons.
7. A frontend flow that asks browser notification permission and subscribes the device.

WebPush.Subject should be a mailto: address or HTTPS URL. Do not use localhost as a VAPID subject.

SSE vs Web Push

Use both transports:

Transport	Purpose
SSE (/auth/v1/subscribe)	Live UI updates while the app is open
Web Push (/auth/v1/notifications/*)	Background notification tray delivery

Do not disable SSE after enabling Web Push. Active tabs still rely on SSE for live state, cursor recovery, and immediate UI refresh.

User Controls

There are two separate concepts:

Control	Meaning
Device notifications	Enable or disable this browser/device subscription
Mute all	Disable push delivery for the whole user account

Turning off notifications on one phone should not disable notifications on every other device.

iPhone Support

iPhone support exists, but only under Apple’s Web Push rules:

• iOS 16.4 or newer.
• The site must be installed to the Home Screen as a PWA.
• The user must open the installed PWA, not a normal Safari/Chrome tab.
• HTTPS, manifest, and service worker must be valid.
• The user must grant notification permission.

Chrome on iOS uses WebKit, so the same installed-PWA restriction applies.

Android Notes

On Android Chrome/Edge, the provider is usually FCM.

Delivery can be accepted by FCM but still not appear as a heads-up alert if:

• site notifications are blocked,
• OS-level notifications for the browser are blocked,
• the notification channel is silent,
• battery optimization delays background work,
• the service worker has not updated yet,
• repeated notifications reuse a tag and only update an existing notification.

Sound, vibration, and heads-up behavior are ultimately controlled by Android notification channels and OS settings. The server and service worker can provide hints, but they cannot force sound on a muted channel.

Testing

Use /ProxyAdmin/PushSubscriptions:

1. Confirm that the subscription is active.
2. Check the endpoint host (fcm.googleapis.com, web.push.apple.com, etc.).
3. Press Test.
4. Confirm last_success_utc changes.

If the test says it was accepted by the push service, AuthProxy reached the browser vendor. If nothing appears on the device, troubleshoot the browser/OS/service-worker layer.

The test validates the Web Push sender transport. It does not validate the full business-event pipeline from Chat, TrexWallet, CRM, or Core.

Troubleshooting

Symptom	Likely cause
public_key returns 401	User session expired; reload or sign in again
public_key returns 503	Web Push is disabled or VAPID config is missing
Subscribe fails after deployment	Database schema or VAPID key mismatch
Test accepted, but no device notification	Browser/OS/service-worker display issue
Test returns 404/410	Browser endpoint expired; resubscribe the device
Test works, real events do not	Module events are not reaching AuthProxy EventPoller or PushDispatcher mapping
Notification appears silently	OS notification channel or browser notification settings

Operational Checklist

• Keep one active PushSending node per deployment.
• Keep /sw.js owned by the platform root PWA and do not overwrite it from customer Core builds.
• Keep SSE enabled.
• Regenerate browser subscriptions after VAPID key rotation.
• Use /ProxyAdmin/PushSubscriptions during stand validation.
• Tell iPhone users to install the PWA before enabling notifications.

Related API

The endpoint-level contract is documented in Authentication API.