familysync/.planning/milestones/v1.0-phases/05-web-push-notifications/05-02-PLAN.md at main

Files

T

Lucas Berger 982438dc10 style(13-03): apply Prettier formatting across repo

Mechanical reformat — no logic changes. 398 files changed, 19125
insertions(+), 16457 deletions(-). Prettier 3.8.4 with .prettierrc
(singleQuote:true, semi:true, tabWidth:2, trailingComma:all,
printWidth:100). Isolated per D-13-08 for reviewability.

2026-06-11 20:35:18 -04:00

6.3 KiB

Raw Permalink Blame History

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase

plan

type

wave

depends_on

files_modified

autonomous

requirements

must_haves

05-web-push-notifications

tdd

05-01

apps/api/src/lib/pushDispatcher.ts

apps/api/tests/lib/pushDispatcher.test.ts

true

NOTIF-01

NOTIF-02

NOTIF-03

truths

artifacts

key_links

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

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

</threat_model>

- RED commit precedes GREEN; pushDispatcher.test.ts green. - `pnpm --filter @familysync/api typecheck` passes.

<success_criteria>

Failing test written and committed (RED).
dispatchPush + buildPushBody implemented; test passes (GREEN).
410/404 prune verified; transient/success no-prune verified. </success_criteria>

Create `.planning/phases/05-web-push-notifications/05-02-SUMMARY.md` with RED/GREEN/REFACTOR commits.

6.3 KiB Raw Permalink Blame History

Trust Boundaries

STRIDE Threat Register

6.3 KiB

Raw Permalink Blame History