48 lines
2.2 KiB
Markdown
48 lines
2.2 KiB
Markdown
**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.
|