fix(api): derive secure sse subscriptions

2026-03-30 14:20:18 +02:00
parent 27b0e38b93
commit 82466a4e34
7 changed files with 281 additions and 29 deletions
@@ -0,0 +1,45 @@
+**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.