Push Notifications

---
name: push-notifications
description: Web Push — service worker, VAPID, permission UX, subscriptions, browser support, security.
---

## Decision Table — What to Load

| Task | Load |
|------|------|
| Cross-browser support, Safari quirks, iOS PWA, framework integration | `references/browser-compatibility.md` |
| SW registration, permission flow, subscribing, push/click event handlers | `references/service-worker.md` |
| VAPID key generation, subscription storage, expiry, server-side sending | `references/subscription-management.md` |

Load only the reference(s) relevant to the current task.

---

## Core Rules (apply without loading references)

- **HTTPS required** — service workers do not register on plain HTTP (`localhost` is the only exception)
- **Never request permission on page load** — always tie the prompt to an explicit user action
- **`userVisibleOnly: true`** is mandatory in `pushManager.subscribe()` — Chrome rejects without it
- **VAPID private key is server-side only** — never in the frontend bundle
- **iOS push = PWA only** — does not work in the Safari browser tab; show "Add to Home Screen" first
- **Delete 410/404 subscriptions immediately** — they are permanently invalid
- **Design for `title` + `body` + `icon` only** — `actions`, `image`, `badge`, `vibrate` are progressive enhancement

---

## Prerequisites

1. HTTPS (or `localhost`)
2. Registered and active service worker
3. VAPID key pair generated and stored (`npx web-push generate-vapid-keys`)

---

## Quick-Start Flow

1. Register SW on app load (do not prompt yet)
2. On user action → check `Notification.permission` → show double opt-in UI → call `Notification.requestPermission()`
3. On grant → `pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: <vapid-public> })`
4. POST subscription object to backend → store per authenticated user
5. SW handles `push` event → `showNotification()`
6. SW handles `notificationclick` → focus or open the target URL
7. SW handles `pushsubscriptionchange` → resubscribe and update backend
8. Backend: delete subscriptions on 410/404; retry on 429 with backoff

---

## Security Checklist

- [ ] VAPID private key is server-side only — never in the frontend bundle
- [ ] `applicationServerKey` (public) is safe to expose in the bundle
- [ ] Subscription endpoints stored with the authenticated user — never accessible cross-user
- [ ] Push payload is validated on the server before sending
- [ ] No PII in the push payload — notification body is visible on the lock screen
- [ ] Backend deletes 410 subscriptions immediately to avoid endpoint enumeration
- [ ] HTTPS enforced end-to-end (required by spec)

---

## Implementation Checklist

- [ ] Feature detection — push opt-in UI hidden when not supported
- [ ] iOS PWA detection — "Add to Home Screen" prompt shown before permission request on iOS
- [ ] Permission requested only on explicit user action (never on page load)
- [ ] `pushsubscriptionchange` event handled in SW
- [ ] Subscription sent to backend and stored per authenticated user
- [ ] `notificationclick` opens correct URL and focuses existing tab if open
- [ ] Notifications work without `actions`/`image` (progressive enhancement)
- [ ] Backend deletes 410/404 subscriptions
- [ ] VAPID private key not in frontend bundle
- [ ] Safari macOS: `push_server_url` in manifest
- [ ] iOS: push tested in installed PWA, not browser tab
- [ ] No PII in notification body or payload