Push Notifications

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# Web Push Subscription Flow
 
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web App       │    │   Service       │    │   Push          │    │   Your          │
│   (Browser)     │    │   Worker        │    │   Service       │    │   Server        │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │                      │
         │  1. Register SW      │                      │                      │
         │  ─────────────────>  │                      │                      │
         │                      │                      │                      │
         │  2. Request Push     │                      │                      │
         │     Permission       │                      │                      │
         │  <────────────────── │                      │                      │
         │                      │                      │                      │
         │  3. User Grants      │                      │                      │
         │     Permission       │                      │                      │
         │  ─────────────────>  │                      │                      │
         │                      │                      │                      │
         │  4. Subscribe to     │                      │                      │
         │     Push Manager     │                      │                      │
         │  ─────────────────────────────────────────> │                      │
         │                      │                      │                      │
         │  5. PushSubscription │                      │                      │
         │     (endpoint + keys)│                      │                      │
         │  <───────────────────────────────────────── │                      │
         │                      │                      │                      │
         │  6. Send Subscription to Server             │                      │
         │  ────────────────────────────────────────────────────────────────> │
         │                      │                      │                      │
         │                      │                      │    7. Store          │
         │                      │                      │    Subscription      │
         │                      │                      │                      │

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Web Push Message Delivery Flow
 
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Your          │    │   Push          │    │   Service       │    │   Web App       │
│   Server        │    │   Service       │    │   Worker        │    │   (Browser)     │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │                      │
         │  1. POST to endpoint │                      │                      │
         │     (encrypted payload)                     │                      │
         │  ─────────────────>  │                      │                      │
         │                      │                      │                      │
         │  2. 201 Created      │                      │                      │
         │  <───────────────────│                      │                      │
         │                      │                      │                      │
         │                      │  3. Deliver to       │                      │
         │                      │     Browser          │                      │
         │                      │  ────────────────>   │                      │
         │                      │                      │                      │
         │                      │                      │  4. 'push' event     │
         │                      │                      │  fired in SW         │
         │                      │                      │                      │
         │                      │                      │  5. SW handles       │
         │                      │                      │  shows notification  │
         │                      │                      │  ──────────────────> │
         │                      │                      │                      │
         │                      │                      │  6. User clicks      │
         │                      │                      │  <────────────────── │
         │                      │                      │                      │
         │                      │                      │  7. Open app/URL     │
         │                      │                      │  ──────────────────> │

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

// service-worker.js - Web Push Event Handler
 
// Push event fires when a push message is received
self.addEventListener('push', function(event) {
    console.log('[Service Worker] Push received:', event);
    
    let notificationData = {
        title: 'Default Title',
        body: 'Default body text',
        icon: '/icons/notification-icon.png',
        badge: '/icons/badge-icon.png',
        data: {}
    };
    
    // Extract payload if present
    if (event.data) {
        try {
            const payload = event.data.json();
            notificationData = {
                title: payload.title || notificationData.title,
                body: payload.body || notificationData.body,
                icon: payload.icon || notificationData.icon,
                badge: payload.badge || notificationData.badge,
                data: payload.data || {},
                
                // Additional options
                image: payload.image,  // Large image to display
                actions: payload.actions,  // Action buttons
                tag: payload.tag,  // Group/replace notifications
                renotify: payload.renotify,  // Vibrate on replace
                requireInteraction: payload.requireInteraction,
                silent: payload.silent,
                timestamp: payload.timestamp,
            };
        } catch (e) {
            // Text payload
            notificationData.body = event.data.text();
        }
    }
    
    // IMPORTANT: Must call waitUntil to keep SW alive during async operation
    event.waitUntil(
        self.registration.showNotification(notificationData.title, {
            body: notificationData.body,
            icon: notificationData.icon,
            badge: notificationData.badge,
            image: notificationData.image,
            actions: notificationData.actions,
            tag: notificationData.tag,
            data: notificationData.data,
            requireInteraction: notificationData.requireInteraction,
            silent: notificationData.silent,
            timestamp: notificationData.timestamp,
        })
    );
});
 
// Notification click event
self.addEventListener('notificationclick', function(event) {
    console.log('[Service Worker] Notification clicked:', event);
    
    event.notification.close();  // Close the notification
    
    // Get data from the notification
    const notificationData = event.notification.data;
    const actionClicked = event.action;  // Which action button was clicked
    
    let targetUrl = notificationData.url || '/';
    
    // Handle specific action buttons
    if (actionClicked === 'reply') {
        targetUrl = notificationData.replyUrl || '/reply';
    } else if (actionClicked === 'dismiss') {
        // Just close, don't open anything
        return;
    }
    
    // Open or focus the appropriate window
    event.waitUntil(
        clients.matchAll({ type: 'window', includeUncontrolled: true })
            .then(function(clientList) {
                // Check if a window is already open
                for (const client of clientList) {
                    if (client.url.includes(self.location.origin) && 'focus' in client) {
                        client.focus();
                        return client.navigate(targetUrl);
                    }
                }
                // No existing window - open new one
                return clients.openWindow(targetUrl);
            })
    );
});
 
// Notification close event (dismissed without clicking)
self.addEventListener('notificationclose', function(event) {
    console.log('[Service Worker] Notification closed:', event);
    
    // Track dismissal for analytics
    const notificationData = event.notification.data;
    
    event.waitUntil(
        // Send analytics event (fire and forget)
        fetch('/api/notifications/dismissed', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                notificationId: notificationData.notificationId,
                timestamp: Date.now()
            })
        }).catch(() => {
            // Ignore errors - analytics is best-effort
        })
    );
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

// Client-side push subscription management
 
class WebPushManager {
    constructor(vapidPublicKey, serverEndpoint) {
        // VAPID public key (base64url encoded)
        this.vapidPublicKey = vapidPublicKey;
        this.serverEndpoint = serverEndpoint;
        this.swRegistration = null;
    }
    
    async initialize() {
        // Check browser support
        if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
            throw new Error('Push notifications not supported');
        }
        
        // Register service worker
        this.swRegistration = await navigator.serviceWorker.register('/sw.js');
        console.log('Service Worker registered:', this.swRegistration);
        
        // Wait for the service worker to be ready
        await navigator.serviceWorker.ready;
        
        return this;
    }
    
    async getPermissionState() {
        const permission = await this.swRegistration.pushManager.permissionState({
            userVisibleOnly: true
        });
        return permission;  // 'granted', 'denied', or 'prompt'
    }
    
    async subscribe() {
        // Request permission
        const permission = await Notification.requestPermission();
        
        if (permission !== 'granted') {
            throw new Error('Notification permission denied');
        }
        
        // Subscribe to push
        const subscription = await this.swRegistration.pushManager.subscribe({
            userVisibleOnly: true,  // Required: must show notification
            applicationServerKey: this.urlBase64ToUint8Array(this.vapidPublicKey)
        });
        
        console.log('Push subscription:', JSON.stringify(subscription));
        
        // Send subscription to server
        await this.sendSubscriptionToServer(subscription);
        
        return subscription;
    }
    
    async unsubscribe() {
        const subscription = await this.swRegistration.pushManager.getSubscription();
        
        if (subscription) {
            // Unsubscribe from push
            await subscription.unsubscribe();
            
            // Notify server
            await fetch(`${this.serverEndpoint}/unsubscribe`, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ endpoint: subscription.endpoint })
            });
        }
    }
    
    async getExistingSubscription() {
        return await this.swRegistration.pushManager.getSubscription();
    }
    
    async sendSubscriptionToServer(subscription) {
        const response = await fetch(`${this.serverEndpoint}/subscribe`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(subscription.toJSON())
        });
        
        if (!response.ok) {
            throw new Error('Failed to save subscription on server');
        }
    }
    
    // Convert base64url to Uint8Array for applicationServerKey
    urlBase64ToUint8Array(base64String) {
        const padding = '='.repeat((4 - base64String.length % 4) % 4);
        const base64 = (base64String + padding)
            .replace(/\-/g, '+')
            .replace(/_/g, '/');
        
        const rawData = window.atob(base64);
        const outputArray = new Uint8Array(rawData.length);
        
        for (let i = 0; i < rawData.length; ++i) {
            outputArray[i] = rawData.charCodeAt(i);
        }
        
        return outputArray;
    }
}
 
// Usage
const pushManager = new WebPushManager(
    'BBr5GIeWhPvVjaGk8HQ5F4P3GnN...',  // Your VAPID public key
    '/api/push'
);
 
await pushManager.initialize();
 
// Check current state
if (await pushManager.getExistingSubscription()) {
    console.log('Already subscribed');
} else if (await pushManager.getPermissionState() !== 'denied') {
    // Can request subscription
    await pushManager.subscribe();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# VAPID JWT generation for Web Push
 
import jwt
import time
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.backends import default_backend
import base64
 
class VAPIDAuthenticator:
    """
    Generates VAPID authentication headers for web push requests.
    
    VAPID JWT claims:
    - aud: The push service origin (e.g., https://fcm.googleapis.com)
    - exp: Expiration time (max 24 hours from iat)
    - sub: Contact information (mailto: or https: URL)
    """
    
    # JWT valid for 12 hours (less than 24 hour max)
    TOKEN_LIFETIME_SECONDS = 43200
    
    def __init__(self, private_key_pem: str, public_key_bytes: bytes, contact_info: str):
        """
        Initialize with VAPID key pair.
        
        Args:
            private_key_pem: PEM-encoded EC private key
            public_key_bytes: Raw public key bytes (65 bytes for P-256)
            contact_info: Your contact URL (mailto:email or https://url)
        """
        self.private_key = serialization.load_pem_private_key(
            private_key_pem.encode(),
            password=None,
            backend=default_backend()
        )
        self.public_key_bytes = public_key_bytes
        self.contact_info = contact_info
        
        # Cache tokens per audience
        self._token_cache = {}
    
    @classmethod
    def generate_keypair(cls) -> tuple[str, str, bytes]:
        """
        Generate a new VAPID key pair.
        
        Returns:
            Tuple of (private_key_pem, public_key_base64url, public_key_bytes)
        """
        private_key = ec.generate_private_key(ec.SECP256R1(), default_backend())
        
        # Export private key as PEM
        private_pem = private_key.private_bytes(
            encoding=serialization.Encoding.PEM,
            format=serialization.PrivateFormat.PKCS8,
            encryption_algorithm=serialization.NoEncryption()
        ).decode()
        
        # Export public key as uncompressed point
        public_key = private_key.public_key()
        public_bytes = public_key.public_bytes(
            encoding=serialization.Encoding.X962,
            format=serialization.PublicFormat.UncompressedPoint
        )
        
        # Base64url encode for client-side use
        public_base64url = base64.urlsafe_b64encode(public_bytes).rstrip(b'=').decode()
        
        return private_pem, public_base64url, public_bytes
    
    def get_authorization_headers(self, push_service_origin: str) -> dict:
        """
        Get the headers required for VAPID authentication.
        
        Args:
            push_service_origin: The origin of the push service
                               (e.g., https://fcm.googleapis.com)
        
        Returns:
            Dict with Authorization and Crypto-Key headers
        """
        token = self._get_token(push_service_origin)
        
        return {
            'Authorization': f'vapid t={token}, k={self._get_public_key_base64url()}',
            # Alternative header format (older):
            # 'Authorization': f'WebPush {token}',
            # 'Crypto-Key': f'p256ecdsa={self._get_public_key_base64url()}'
        }
    
    def _get_token(self, audience: str) -> str:
        """
        Get a valid JWT for the given audience, using cache when possible.
        """
        now = time.time()
        
        # Check cache
        cached = self._token_cache.get(audience)
        if cached and cached['expires_at'] > now + 300:  # 5 min buffer
            return cached['token']
        
        # Generate new token
        token = self._generate_token(audience, now)
        
        self._token_cache[audience] = {
            'token': token,
            'expires_at': now + self.TOKEN_LIFETIME_SECONDS
        }
        
        return token
    
    def _generate_token(self, audience: str, issued_at: float) -> str:
        """Generate a new VAPID JWT."""
        payload = {
            'aud': audience,
            'exp': int(issued_at) + self.TOKEN_LIFETIME_SECONDS,
            'sub': self.contact_info,
        }
        
        return jwt.encode(payload, self.private_key, algorithm='ES256')
    
    def _get_public_key_base64url(self) -> str:
        """Get base64url-encoded public key."""
        return base64.urlsafe_b64encode(self.public_key_bytes).rstrip(b'=').decode()
 
 
# One-time key generation
private_pem, public_base64url, public_bytes = VAPIDAuthenticator.generate_keypair()
print(f"Public key for client: {public_base64url}")
# Save private_pem securely!
 
# Runtime usage
vapid = VAPIDAuthenticator(
    private_key_pem=private_pem,
    public_key_bytes=public_bytes,
    contact_info="mailto:admin@yourapp.com"
)
 
# Get headers for a push request
headers = vapid.get_authorization_headers("https://fcm.googleapis.com")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# Web Push message encryption
# In practice, use a library like pywebpush, but here's the concept:
 
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
import struct
 
class WebPushEncryptor:
    """
    Encrypts web push message payloads using aes128gcm encoding.
    
    The encryption uses:
    1. ECDH key agreement between sender and receiver
    2. HKDF key derivation for the actual encryption key
    3. AES-128-GCM for content encryption
    
    NOTE: This is a simplified illustration. Use a production library
    like 'pywebpush' for actual implementations.
    """
    
    def encrypt(
        self,
        plaintext: bytes,
        subscription: dict
    ) -> tuple[bytes, bytes, bytes]:
        """
        Encrypt a message for web push delivery.
        
        Args:
            plaintext: The notification payload (JSON bytes)
            subscription: PushSubscription object with keys
        
        Returns:
            Tuple of (ciphertext, salt, server_public_key)
        """
        # Extract receiver's keys from subscription
        receiver_public_key = base64url_decode(subscription['keys']['p256dh'])
        auth_secret = base64url_decode(subscription['keys']['auth'])
        
        # Generate ephemeral sender key pair
        sender_private_key = ec.generate_private_key(ec.SECP256R1())
        sender_public_key = sender_private_key.public_key()
        
        # ECDH shared secret
        shared_secret = sender_private_key.exchange(
            ec.ECDH(),
            ec.EllipticCurvePublicKey.from_encoded_point(
                ec.SECP256R1(),
                receiver_public_key
            )
        )
        
        # Generate salt
        salt = os.urandom(16)
        
        # Derive encryption key using HKDF
        # This follows the Web Push encryption specification
        
        # PRK = HKDF-Extract(auth_secret, ecdh_shared_secret)
        prk = HKDF(
            algorithm=hashes.SHA256(),
            length=32,
            salt=auth_secret,
            info=b'WebPush: info\x00' + receiver_public_key + sender_public_key_bytes,
        ).derive(shared_secret)
        
        # Derive content encryption key
        cek = HKDF(
            algorithm=hashes.SHA256(),
            length=16,
            salt=salt,
            info=b'Content-Encoding: aes128gcm\x00',
        ).derive(prk)
        
        # Derive nonce
        nonce = HKDF(
            algorithm=hashes.SHA256(),
            length=12,
            salt=salt,
            info=b'Content-Encoding: nonce\x00',
        ).derive(prk)
        
        # Pad plaintext (required by spec)
        # Record size is typically 4096 bytes
        padded = self._pad(plaintext, 4096)
        
        # Encrypt with AES-128-GCM
        aesgcm = AESGCM(cek)
        ciphertext = aesgcm.encrypt(nonce, padded, None)
        
        # Build encrypted content block
        # Format: salt (16) | rs (4) | idlen (1) | keyid | ciphertext
        sender_public_key_bytes = sender_public_key.public_bytes(
            encoding=serialization.Encoding.X962,
            format=serialization.PublicFormat.UncompressedPoint
        )
        
        record_size = 4096
        encrypted_content = (
            salt +
            struct.pack('>I', record_size) +  # 4 bytes big-endian
            struct.pack('B', len(sender_public_key_bytes)) +  # 1 byte
            sender_public_key_bytes +
            ciphertext
        )
        
        return encrypted_content
    
    def _pad(self, data: bytes, record_size: int) -> bytes:
        """
        Pad data according to aes128gcm requirements.
        
        Padding: delimiter (0x02) + zero padding to reach record size
        (minus 16 bytes for auth tag, minus 1 for delimiter min)
        """
        max_data_size = record_size - 17  # 16 for tag, 1 for delimiter
        
        if len(data) > max_data_size:
            raise ValueError("Data too large for record size")
        
        padding_length = max_data_size - len(data)
        return data + b'\x02' + (b'\x00' * padding_length)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187

# Complete web push sending implementation using pywebpush
 
from pywebpush import webpush, WebPushException
import json
 
class WebPushService:
    """
    Service for sending web push notifications.
    
    Uses pywebpush library which handles:
    - VAPID authentication
    - Payload encryption (aes128gcm)
    - Proper header formatting
    """
    
    def __init__(
        self,
        vapid_private_key: str,
        vapid_claims: dict
    ):
        """
        Initialize with VAPID credentials.
        
        Args:
            vapid_private_key: Your VAPID private key (base64url or PEM)
            vapid_claims: Dict with 'sub' claim (mailto: or https: URL)
        """
        self.vapid_private_key = vapid_private_key
        self.vapid_claims = vapid_claims
    
    def send(
        self,
        subscription: dict,
        payload: dict,
        ttl: int = 86400,
        urgency: str = 'normal',
        topic: str | None = None
    ) -> SendResult:
        """
        Send a push notification to a subscription.
        
        Args:
            subscription: The PushSubscription object from the browser
                         {endpoint, keys: {p256dh, auth}}
            payload: Notification data (will be JSON serialized)
            ttl: Time-to-live in seconds (how long service keeps message)
            urgency: 'very-low', 'low', 'normal', or 'high'
            topic: Optional topic for message replacement
        
        Returns:
            SendResult with success status and details
        """
        try:
            # Prepare headers
            headers = {}
            if urgency:
                headers['Urgency'] = urgency
            if topic:
                headers['Topic'] = topic
            
            # Send the push
            response = webpush(
                subscription_info=subscription,
                data=json.dumps(payload),
                vapid_private_key=self.vapid_private_key,
                vapid_claims=self.vapid_claims,
                ttl=ttl,
                headers=headers
            )
            
            return SendResult(
                success=True,
                status_code=response.status_code,
                message_id=response.headers.get('Location')
            )
            
        except WebPushException as e:
            return self._handle_error(e, subscription)
    
    def send_batch(
        self,
        subscriptions: list[dict],
        payload: dict,
        ttl: int = 86400
    ) -> BatchSendResult:
        """
        Send the same notification to multiple subscriptions.
        
        Note: Web push doesn't have a native batch API like FCM.
        We send individual requests (can be parallelized).
        """
        results = []
        
        for subscription in subscriptions:
            result = self.send(subscription, payload, ttl)
            results.append(result)
        
        return BatchSendResult(
            total=len(subscriptions),
            successful=sum(1 for r in results if r.success),
            failed=sum(1 for r in results if not r.success),
            results=results
        )
    
    def _handle_error(
        self,
        error: WebPushException,
        subscription: dict
    ) -> SendResult:
        """
        Handle web push errors with appropriate actions.
        """
        status_code = error.response.status_code if error.response else None
        
        # 404 or 410: Subscription no longer valid
        if status_code in (404, 410):
            return SendResult(
                success=False,
                status_code=status_code,
                error='SUBSCRIPTION_INVALID',
                should_remove=True  # Flag to remove from database
            )
        
        # 429: Rate limited
        if status_code == 429:
            retry_after = error.response.headers.get('Retry-After', 60)
            return SendResult(
                success=False,
                status_code=status_code,
                error='RATE_LIMITED',
                retry_after=int(retry_after)
            )
        
        # 5xx: Server error
        if status_code and status_code >= 500:
            return SendResult(
                success=False,
                status_code=status_code,
                error='SERVER_ERROR',
                should_retry=True
            )
        
        # Other errors
        return SendResult(
            success=False,
            status_code=status_code,
            error=str(error),
            should_retry=False
        )
 
 
# Usage example
push_service = WebPushService(
    vapid_private_key='YOUR_PRIVATE_KEY_BASE64URL_OR_PEM',
    vapid_claims={
        'sub': 'mailto:admin@yourapp.com'
    }
)
 
# Subscription from browser
subscription = {
    'endpoint': 'https://fcm.googleapis.com/fcm/send/...',
    'keys': {
        'p256dh': 'user_public_key_base64url',
        'auth': 'auth_secret_base64url'
    }
}
 
# Send notification
result = push_service.send(
    subscription=subscription,
    payload={
        'title': 'New Message',
        'body': 'You have a new message from John',
        'icon': '/icons/message.png',
        'data': {
            'url': '/messages/123',
            'messageId': '123'
        }
    },
    ttl=86400,  # 24 hours
    urgency='high'
)
 
if result.should_remove:
    # Remove invalid subscription from database
    db.delete_subscription(subscription['endpoint'])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// Browser-specific push handling
 
class PushCapabilities {
    static detect() {
        const capabilities = {
            serviceWorker: 'serviceWorker' in navigator,
            pushManager: 'PushManager' in window,
            notification: 'Notification' in window,
            getSubscription: false,
            
            // Browser-specific
            browser: this.detectBrowser(),
            isIOS: /iPad|iPhone|iPod/.test(navigator.userAgent),
            isMacOS: /Macintosh/.test(navigator.userAgent),
            isAndroid: /Android/.test(navigator.userAgent),
            
            // Additional capabilities
            permissionState: null,
            canPrompt: false,
        };
        
        return capabilities;
    }
    
    static detectBrowser() {
        const ua = navigator.userAgent;
        
        if (/Safari/.test(ua) && !/Chrome/.test(ua)) {
            return 'safari';
        } else if (/Firefox/.test(ua)) {
            return 'firefox';
        } else if (/Edg/.test(ua)) {
            return 'edge';
        } else if (/Chrome/.test(ua)) {
            return 'chrome';
        } else if (/Opera|OPR/.test(ua)) {
            return 'opera';
        }
        
        return 'unknown';
    }
    
    static async getPermissionState() {
        if (!('Notification' in window)) {
            return 'unsupported';
        }
        
        // Check current permission
        if (Notification.permission === 'granted') {
            return 'granted';
        }
        
        if (Notification.permission === 'denied') {
            return 'denied';
        }
        
        return 'prompt';  // Can ask for permission
    }
    
    static isSafariIOS() {
        return /iPad|iPhone|iPod/.test(navigator.userAgent) &&
               /Safari/.test(navigator.userAgent) &&
               !('chrome' in window);
    }
    
    static isPWA() {
        return window.matchMedia('(display-mode: standalone)').matches ||
               window.navigator.standalone === true;
    }
    
    static canReceivePush() {
        const caps = this.detect();
        
        // iOS Safari requires PWA
        if (this.isSafariIOS()) {
            return this.isPWA();
        }
        
        return caps.serviceWorker && caps.pushManager && caps.notification;
    }
}
 
// Usage
async function initializePush() {
    const caps = PushCapabilities.detect();
    
    if (!PushCapabilities.canReceivePush()) {
        if (PushCapabilities.isSafariIOS() && !PushCapabilities.isPWA()) {
            // Show iOS PWA installation prompt
            showAddToHomeScreenPrompt();
            return;
        }
        
        // Push not supported
        console.log('Push notifications not supported');
        return;
    }
    
    const permissionState = await PushCapabilities.getPermissionState();
    
    if (permissionState === 'denied') {
        // User has blocked - show guidance to unblock
        showUnblockInstructions();
        return;
    }
    
    if (permissionState === 'granted') {
        // Already subscribed - ensure subscription is saved
        await ensureSubscriptionSaved();
    } else {
        // Can request - show opt-in UI
        showPushOptInUI();
    }
}