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)
path
provides
exports
min_lines
apps/api/src/lib/pushDispatcher.ts
dispatchPush(subscription, notification, dbRowId) — single send + prune helper
dispatchPush
buildPushBody
30
from
to
via
pattern
apps/api/src/lib/pushDispatcher.ts
push_subscriptions table
db.delete on 410/404
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.
<threat_model>
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
