familysync/.planning/phases/04-shared-lists-live-sync/04-02-PLAN.md

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

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	user_setup	must_haves
04-shared-lists-live-sync	02	tdd	2	04-01	apps/api/src/lib/listEmitter.ts apps/api/tests/lib/listEmitter.test.ts apps/api/src/lib/listAccess.ts apps/api/src/lib/listAccess.test.ts	true	LIST-04		truths artifacts key_links An event published for a list is delivered only to subscribers of that list's channel A subscriber to list A receives no events published for list B getAccessibleListIds(userId) returns owned list ids plus list ids shared via list_shares, and nothing else Unsubscribing stops further delivery to that handler path provides exports apps/api/src/lib/listEmitter.ts in-memory scoped pub/sub: publishListEvent, subscribeListEvents publishListEvent subscribeListEvents ListEvent path provides exports apps/api/src/lib/listAccess.ts getAccessibleListIds(userId) access-scope query getAccessibleListIds path provides contains apps/api/tests/lib/listEmitter.test.ts scoped fan-out correctness tests (D-04) describe from to via pattern apps/api/src/lib/listEmitter.ts node:events EventEmitter module-level singleton keyed by list:${listId} emit(`list: from to via pattern apps/api/src/lib/listAccess.ts lists + list_shares tables owner_id OR list_shares.user_id query listShares

Build and test-first the load-bearing live-sync primitive: an in-memory, per-list-scoped event emitter (`listEmitter.ts`) plus the access-scope query (`listAccess.ts`) that together guarantee D-04 — a list's change events reach ONLY members with access to that list, never all connected clients and never non-shared members.

This is a dedicated TDD plan because it is pure, testable business logic (expect(deliveredEvents).toEqual([...])) and it is the single highest-correctness-risk seam in the phase (private-list leakage). The SSE endpoint (Plan 06) and the route fan-out triggers (Plans 03–06) consume these two functions.

Purpose: Get scoped fan-out provably correct in isolation before any SSE wiring, with the negative test ("private-list events NOT delivered to a non-owner") proven green. Output: publishListEvent/subscribeListEvents (in-memory EventEmitter singleton) and getAccessibleListIds(userId), both fully unit-tested.

Fan-out mechanism justification (D-18): In-memory EventEmitter, not Redis. The API runs as a single Node process (no replicas), so Redis pub/sub adds a network hop, an ioredis dependency, and operational overhead for zero benefit. D-18 (N-member / multi-process-agnostic design) is satisfied by the abstraction boundary: callers use publishListEvent/subscribeListEvents and never touch the EventEmitter directly, so a future Redis swap is mechanical inside listEmitter.ts. ioredis is intentionally NOT installed in Phase 4.

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md @.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md @.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md @.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md @apps/api/src/db/schema.ts @apps/api/src/db/client.ts Scoped in-memory list event fan-out + access-scope query (D-04) apps/api/src/lib/listEmitter.ts, apps/api/tests/lib/listEmitter.test.ts, apps/api/src/lib/listAccess.ts, apps/api/src/lib/listAccess.test.ts - apps/api/tests/lib/listEmitter.test.ts (RED stub from Plan 01 — convert to real assertions) - apps/api/src/db/schema.ts (lists, listShares tables created in Plan 01) - apps/api/src/routes/events.ts lines 1-110 (db query + drizzle and/or/eq conventions) - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 1 + Finding 3 (verbatim patterns) - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/lib/listEmitter.ts" listEmitter (pure, no DB): - Test 1 (RED first): publishListEvent(1, ev) delivers ev to a handler subscribed via subscribeListEvents(1, h); handler called exactly once with ev. - Test 2 (the D-04 negative, critical): a handler subscribed to list 1 receives NOTHING when publishListEvent(2, ev) is called. This is the "private-list events NOT emitted to a non-owner subscriber" assertion from 04-VALIDATION.md. - Test 3: the unsubscribe function returned by subscribeListEvents stops delivery — after calling it, a subsequent publish to that list does not invoke the handler. - Test 4: multiple handlers on the same list channel all receive the event. - ListEvent type union: 'item:added' | 'item:updated' | 'item:deleted' | 'list:updated' | 'list:deleted', shape { type, listId, payload }.

listAccess (DB-backed, uses the test DB harness from Plan 01):
- Test 5: getAccessibleListIds returns ids of lists the user OWNS.
- Test 6: getAccessibleListIds returns ids of lists shared to the user via list_shares.
- Test 7 (D-04): getAccessibleListIds does NOT return another user's private (non-shared, non-owned) list id.
- Test 8: result has no duplicates when a list is both owned and (erroneously) shared.

listEmitter.ts: module-level `new EventEmitter()` with setMaxListeners(200); channel key `list:${listId}`; publishListEvent emits, subscribeListEvents registers on() and returns an off() closure. Use the RESEARCH Finding 1 pattern verbatim.

listAccess.ts: `getAccessibleListIds(userId: number): Promise<number[]>` — select lists.id where lists.ownerId = userId, union select listShares.listId where listShares.userId = userId, dedupe into a number[]. Use drizzle eq from the events.ts pattern. (Implementation choice: either two selects merged in JS per RESEARCH Finding 3, or a single OR query joined to list_shares — either is acceptable; the tests assert behavior, not query shape.)

Follow RED → GREEN → REFACTOR: write the failing tests first (convert the Plan 01 stub), confirm they fail, implement minimally to green, refactor only if obvious.

<threat_model>

Trust Boundaries

Boundary	Description
publisher (route handler) → subscriber (SSE stream)	A leak here exposes one member's private list to another
API → MariaDB	access-scope query must not over-return list ids

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-04-02	Information Disclosure	scoped fan-out leak (D-04) — load-bearing	mitigate	Per-list channel keying (list:${listId}) + getAccessibleListIds scoped to owner_id OR list_shares; proven by Test 2 (cross-list isolation) and Test 7 (private list excluded)
T-04-03	Information Disclosure	getAccessibleListIds over-returning ids	mitigate	Test 7 asserts a non-owned, non-shared list id is absent; Test 8 asserts dedupe
T-04-04	Denial of Service	EventEmitter max-listeners warning under many SSE connections	accept	setMaxListeners(200) headroom (100 members × 2 devices); single-process scale is bounded for a household app
</threat_model>

pnpm --filter @familysync/api exec vitest run tests/lib/listEmitter.test.ts src/lib/listAccess.test.ts - Test 2 (cross-list isolation) and Test 7 (private list excluded) MUST be present and green.

<success_criteria>

• RED commit: failing listEmitter/listAccess tests (incl. the D-04 negative).
• GREEN commit: implementation passes all tests.
• REFACTOR commit (if any): tests still green.
• ioredis NOT introduced. </success_criteria>

<artifacts_produced> Symbols/files this plan creates (exclude from drift verification):

• apps/api/src/lib/listEmitter.ts exporting publishListEvent(listId, event), subscribeListEvents(listId, handler): () => void, type ListEvent
• apps/api/src/lib/listAccess.ts exporting getAccessibleListIds(userId): Promise<number[]>
• Tests: apps/api/tests/lib/listEmitter.test.ts, apps/api/src/lib/listAccess.test.ts </artifacts_produced>

Create `.planning/phases/04-shared-lists-live-sync/04-02-SUMMARY.md` with RED/GREEN/REFACTOR notes and commit list.