---
phase: 05-web-push-notifications
plan: 02
type: tdd
wave: 2
depends_on: [05-01]
files_modified:
- apps/api/src/lib/pushDispatcher.ts
- apps/api/tests/lib/pushDispatcher.test.ts
autonomous: true
requirements: [NOTIF-01, NOTIF-02, NOTIF-03]
must_haves:
truths:
- 'dispatchPush sends a VAPID-signed push via webpush.sendNotification with the dual-format payload'
- 'On a 410 or 404 from the push service, the subscription row is deleted from push_subscriptions (D-11 prune)'
- 'On 201/transient errors the subscription is NOT deleted; the error is logged and dispatch continues'
- 'The payload body carries both web_push:8030 + notification{} (iOS 18.4+ declarative) AND legacy title/body/tag/data (iOS 16.4-18.3 + Android)'
artifacts:
- path: 'apps/api/src/lib/pushDispatcher.ts'
provides: 'dispatchPush(subscription, notification, dbRowId) — single send + prune helper'
exports: ['dispatchPush', 'buildPushBody']
min_lines: 30
key_links:
- from: 'apps/api/src/lib/pushDispatcher.ts'
to: 'push_subscriptions table'
via: 'db.delete on 410/404'
pattern: "delete\\(pushSubscriptions\\)"
---
TDD the server-side push dispatch primitive: `dispatchPush` signs and sends one notification via `web-push`, builds the iOS-compatible dual-format payload, and prunes a dead subscription (410/404) from the DB. This is the single send path every trigger (reminder, list-change, event-change) calls.
Purpose: Centralising VAPID signing + 410/404 pruning in one tested helper means the three triggers never re-implement crypto or expiry handling. RESEARCH "Don't Hand-Roll" mandates web-push for signing; Pitfall 1/D-11 mandate prune-on-410.
Output: `apps/api/src/lib/pushDispatcher.ts` with `dispatchPush` + `buildPushBody`, turning the Plan 05-01 RED scaffold GREEN.
@.planning/PROJECT.md
@.planning/ROADMAP.md
@apps/api/src/lib/listEmitter.ts
@apps/api/src/db/schema.ts
@apps/api/tests/fixtures/vapid.ts
@.planning/phases/05-web-push-notifications/05-RESEARCH.md
@.planning/phases/05-web-push-notifications/05-PATTERNS.md
@.planning/phases/05-web-push-notifications/05-UI-SPEC.md
pushDispatcher — VAPID send + 410/404 prune
apps/api/src/lib/pushDispatcher.ts, apps/api/tests/lib/pushDispatcher.test.ts
- apps/api/src/lib/listEmitter.ts (module-singleton export idiom)
- apps/api/src/db/schema.ts (pushSubscriptions columns)
- apps/api/tests/fixtures/vapid.ts (TEST_VAPID keypair)
- .planning/phases/05-web-push-notifications/05-RESEARCH.md (Pattern 1 dispatchPush; Pitfall 7 default import; ### Event payload format)
- .planning/phases/05-web-push-notifications/05-UI-SPEC.md (## Notification Content Contract — exact title/body/tag/data templates)
- buildPushBody({title, body, tag, navigate}) → JSON string containing web_push:8030, notification:{title,body,navigate}, AND top-level title/body/tag/data:{url:navigate}. Cases: a reminder payload {title:"Dentist", body:"Starts in 15 min", tag:"reminder-uid", navigate:"/calendar?date=…&event=uid"} round-trips both formats.
- dispatchPush(sub, notification, dbRowId): calls webpush.sendNotification(webPushSub, body, {TTL:300, urgency:'normal'}) where webPushSub = {endpoint, keys:{p256dh, auth}}.
- On thrown err with statusCode===410 → db.delete(pushSubscriptions) where id=dbRowId. Same for 404.
- On statusCode 500/429/network (transient) → NO delete; console.error('[pushDispatcher] …', statusCode, message); resolve (never throw to caller).
- On success (no throw) → no delete, no error.
Test with webpush mocked (vi.mock('web-push')) and db mocked; assert delete called exactly on 410/404 and not otherwise.
Default import `import webpush from 'web-push'` (Pitfall 7 — CommonJS). Do NOT call setVapidDetails at module scope (that happens in index.ts at startup, Plan 05-04) — the dispatcher only calls sendNotification. Export buildPushBody and dispatchPush. Use the eq(pushSubscriptions.id, dbRowId) delete. Log with the '[pushDispatcher]' prefix matching poller.ts convention. Catch unknown, read (err as {statusCode?:number}).statusCode.
cd apps/api && pnpm exec vitest run tests/lib/pushDispatcher.test.ts
Test green: dual-format body asserted; 410 and 404 each trigger one db.delete; transient/success do not; no throw escapes dispatchPush.
## Trust Boundaries
| Boundary | Description |
| ----------------------------- | ----------------------------------------------------------------- |
| API → push service (APNs/FCM) | server signs with VAPID private key; response status is untrusted |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
| --------- | ---------------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| T-05-03 | Cryptography misuse | VAPID signing | mitigate | Use web-push library only; never hand-roll (RESEARCH Don't Hand-Roll) |
| T-05-04 | Denial of Service | malformed push response / per-sub crash | mitigate | dispatchPush catches per-subscription; one failed send never aborts a fan-out loop |
| T-05-05 | Information Disclosure | error logs | mitigate | Log statusCode + err.message only, never the subscription keys or payload body |
- RED commit precedes GREEN; pushDispatcher.test.ts green.
- `pnpm --filter @familysync/api typecheck` passes.
- Failing test written and committed (RED).
- dispatchPush + buildPushBody implemented; test passes (GREEN).
- 410/404 prune verified; transient/success no-prune verified.