CapaKraken/docs/sse-audience-architecture.md

Purpose: Define the secure audience model for realtime SSE delivery so subscribers only receive events that match their server-derived identity and permissions.

Core Rules

• SSE subscriptions are derived on the server from the authenticated database user.
• Clients do not provide arbitrary audience lists.
• Every scoped event declares its audience explicitly.
• Unscoped delivery is disabled for authenticated timeline subscriptions.

Audience Model

Supported canonical audiences:

• user:<userId> for personal notifications and tasks
• role:<systemRole> for role-wide operational events
• permission:<permissionKey> for explicit capability audiences
• resource:<resourceId> for self-service or affected-resource updates

Subscription Flow

1. The web SSE route authenticates the session and loads the database user.
2. The API derives the effective permission set from systemRole + permissionOverrides + roleDefaults.
3. The API builds the canonical subscription audiences from that trusted identity.
4. The event bus subscribes with includeUnscoped: false.
5. Only events whose audience intersects with the derived audience set are delivered.

Event Rules

• Personal events such as notifications must target user:<userId>.
• Planning events may target both permission:manageAllocations and affected resource:<resourceId> audiences.
• Broad operational events must use the smallest real audience that matches the use case.

Contract Tests

The minimum regression suite for this architecture is:

• a standard user does not receive manager planning traffic
• an elevated user does not receive another user's personal events
• multi-audience planning delivery reaches only the matching manager/resource subscribers

Migration Guidance

• New emitters must declare their audiences explicitly instead of relying on global fan-out.
• New SSE endpoints should reuse the same server-side audience derivation instead of rebuilding ad-hoc filters in route handlers.
• If a future feature needs a new audience class, document the audience source of truth before adding the prefix.