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.
• Invalid audience strings fail fast in the event bus.
• Unscoped delivery is disabled for authenticated timeline subscriptions.

Audience Model

Supported canonical audiences:

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

Any other prefix is invalid and must be rejected instead of being accepted silently.

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, typically permission:* rather than role fan-out.

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.