NotificationEvents should only be created if user has permissions to access the related entity

[sleidig]

With different user roles, we see scenarios where the system creates notification events about an entity that the user does not have access to. The notification then shows with an empty link/name in the app (and apart from that is useless and irritating). The backend needs to check permissions and skip events that related to entities that are not accessible.

This means the Config:Permissions doc has to be tracked and parsed in the backend also. It should use a similar approach to the replication-backend service.

• PR: fix: only create notifications for records that user has permission for #131
• depends on Feat: permissions controller replication-backend#221
• migration: update for new permission checking of notification module ndb-setup#88

[sleidig]

Plan: Entity Permission Checks for Notification Events (Issue #117)

Summary

NotificationEvents are created for users who can't access the related entity, causing empty/broken notifications. Fix: aam-services passes Keycloak user UUIDs + the entity doc to a new batch permission-check endpoint on the replication-backend, which handles all identity resolution and CASL evaluation internally, returning allow/deny per user. aam-services skips notifications for denied users.

Approach: Replication-Backend API with UUID-Only Contract

• Single source of truth — all CASL logic + identity resolution lives in replication-backend
• Minimal contract: aam-services sends [UUIDs] + entity doc, gets back results
• Encapsulation: if permission system needs new user fields in the future, only replication-backend changes
• Replication-backend already owns permission rules, CASL evaluation, user variable interpolation, and CouchDB user profile fetching — adding Keycloak admin lookup is a natural extension of its auth infrastructure
• Notification flow is async (queue-based), so network latency is negligible; batch endpoint eliminates per-user round trips
• Trade-off: runtime dependency on replication-backend (already required infrastructure)

Data Flow

Document change → aam-services matches notification rules per user
  → Batch call to replication-backend: { userIds: [UUID1, UUID2, ...], entityDoc: {...}, action: "read" }
  → Replication-backend internally: UUID → Keycloak Admin API (username, roles) → CouchDB (projects) → CASL evaluation
  → Response: { UUID1: permitted, UUID2: denied, ... }
  → aam-services only creates NotificationEvents for permitted users

---

Implementation

Phase 1: Replication-Backend — Permission Check Endpoint + User Resolution

Repo: replication-backend. Independent, no blockers.

1. User Admin Service abstraction — Create abstract UserAdminService base class (Keycloak-independent interface):

   • resolveUser(userId: string): Promise<UserInfo> — resolves UUID → full UserInfo (name, roles, projects)
   • Concrete implementation: KeycloakUserAdminService that calls Keycloak Admin API:
     • GET /admin/realms/{realm}/users/{userId} → username
     • GET /admin/realms/{realm}/users/{userId}/role-mappings/realm → roles[]
   • Uses client credentials grant for authentication
   • Configuration via environment variables: KEYCLOAK_ADMIN_BASE_URL, KEYCLOAK_REALM, KEYCLOAK_ADMIN_CLIENT_ID, KEYCLOAK_ADMIN_CLIENT_SECRET
   • Location: src/permissions/user-identity/

2. User Identity Resolution Service — UserIdentityService that resolves UUID → full UserInfo:

   • Calls UserAdminService.resolveUser() for username + roles
   • Calls existing CouchDBService.get('app', username) for projects (same pattern as JwtBearerStrategy)
   • Constructs UserInfo(id, name, roles, projects)
   • TTL-based in-memory cache (~5 min) per UUID to avoid repeated lookups
   • Location: src/permissions/user-identity/

3. Permission Check Controller — Add PermissionCheckController to existing PermissionModule:

   • POST /permissions/check
   • Request: { userIds: ["uuid1", "uuid2"], entityDoc: { _id: "Child:123", ... }, action: "read" }
   • Response: { "uuid1": { "permitted": true }, "uuid2": { "permitted": false } }
   • For each UUID: resolve via UserIdentityService (cached) → call existing PermissionService.isAllowedTo(action, entityDoc, userInfo, "app") — no new permission logic, reuses the exact same code path as document sync
   • Auth: @UseGuards(CombinedAuthGuard) + @OnlyAuthenticated() (same pattern as AdminController)
   • aam-services authenticates via Basic Auth with shared CouchDB admin credentials
   • Location: src/permissions/permission-check/

4. Update PermissionModule — Register new controller + import KeycloakAdminService/UserIdentityService

5. Tests:

   • Unit: PermissionCheckController with mocked UserIdentityService + PermissionService
   • Unit: UserIdentityService with mocked UserAdminService + CouchDB
   • Unit: KeycloakUserAdminService with mocked HTTP responses
   • Integration: full flow with real CASL evaluation — verifies same result as document sync path (simple rules, conditions, inverted, wildcards)
   • Test caching: second call for same UUID uses cache
   • Test error handling: Keycloak unreachable → clear error response per user

Phase 2: aam-services — Permission Client & Notification Integration

Repo: aam-services. Depends on Phase 1.

6. PermissionCheckClient — HTTP client calling replication-backend /permissions/check:

   • Uses RestClient with Basic Auth (CouchDB admin credentials)
   • Accepts: list of Keycloak UUIDs + entity doc (as Map) + action string
   • Returns: Map<String, Boolean> (UUID → permitted)
   • Location: common/permission/core/PermissionCheckClient.kt
   • Configuration:

     aam-replication-backend-client-configuration:
       base-path: ${REPLICATION_BACKEND_BASE_PATH}
       basic-auth-username: ${COUCH_ADMIN_USER}
       basic-auth-password: ${COUCH_ADMIN_PASSWORD}

7. DI Configuration — PermissionConfiguration.kt in common/permission/di/:

   • RestClient bean for replication-backend
   • PermissionCheckClient bean
   • Activates when replication-backend client config is present (@ConditionalOnProperty(name = ["aam-replication-backend-client-configuration.base-path"]))
   • Lives in common/ — available to any module (notifications, reporting, export, etc.)

8. Wire into notification flow — In DefaultApplyNotificationRulesUseCase, after condition matching:

   • Collect all userIdentifiers (Keycloak UUIDs) whose rules matched
   • Batch call PermissionCheckClient.checkPermissions(userIds, entityDoc, "read")
   • Filter: only publish CreateUserNotificationEvent for users where permitted: true
   • PermissionCheckClient is a required dependency of the notification module (not optional) — if notifications are enabled, the replication-backend config must be provided
   • Location: notification/core/trigger/DefaultApplyNotificationRulesUseCase.kt

9. Graceful failure handling:

   • Replication-backend unreachable at runtime → log warning, skip notification (fail-safe: don't leak data)
   • Micrometer counters: notification.permission.denied, notification.permission.check_failed

10. Tests:

    • Unit: PermissionCheckClient with mocked HTTP responses
    • Unit: DefaultApplyNotificationRulesUseCase with mocked PermissionCheckClient (notification skipped when denied, created when allowed, skipped when check fails)
    • Cucumber: scenarios "notification not created when user cannot read entity", "notification created when user has read permission"
    • Cucumber test setup: WireMock or stub for replication-backend endpoint

11. Deployment configuration:

    • New env vars for aam-services: REPLICATION_BACKEND_BASE_PATH
    • New env vars for replication-backend: KEYCLOAK_ADMIN_BASE_URL, KEYCLOAK_REALM, KEYCLOAK_ADMIN_CLIENT_ID, KEYCLOAK_ADMIN_CLIENT_SECRET
    • Update docker-compose / environment docs
    • Ensure Keycloak client has view-users + view-realm realm-management roles

---

Relevant Files

Replication-backend (create)

• src/permissions/user-identity/user-admin.service.ts — Abstract base class (Keycloak-independent interface)
• src/permissions/user-identity/keycloak-user-admin.service.ts — Keycloak implementation + spec
• src/permissions/user-identity/user-identity.service.ts — UUID → UserInfo resolution + cache + spec
• src/permissions/permission-check/permission-check.controller.ts — Endpoint + spec

Replication-backend (modify)

• src/permissions/permission.module.ts — Register controller + services

Replication-backend (reference)

• src/permissions/permission/permission.service.ts — getAbilityFor(), isAllowedTo() — reuse
• src/permissions/rules/rules.service.ts — getRulesForUser(), injectUserVariablesIntoRules() — reuse
• src/restricted-endpoints/session/user-auth.dto.ts — UserInfo class
• src/admin/admin.controller.ts — Auth guard pattern
• src/auth/guards/jwt-bearer/jwt-bearer.strategy.ts — CouchDB user profile fetch pattern

aam-services (create)

• common/permission/core/PermissionCheckClient.kt — HTTP client
• common/permission/di/PermissionConfiguration.kt — DI config + RestClient bean
• Unit test files

aam-services (modify)

• notification/core/trigger/DefaultApplyNotificationRulesUseCase.kt — Add permission filter
• application.yaml — Replication-backend client config
• Cucumber feature files

aam-services (reference)

• common/auth/core/KeycloakAuthProvider.kt — Client credentials token pattern (reference for replication-backend)
• export/di/AamRenderApiConfiguration.kt — External service RestClient setup
• notification/core/config/DefaultNotificationConfigCache.kt — Caching pattern (reference for replication-backend)

---

Verification

1. Replication-backend: npm test — new endpoint + service tests green
2. aam-services: ./gradlew test --tests "*.permission.*" — permission client tests green
3. No regressions: ./gradlew test (aam-services) + npm test (replication-backend)
4. Cucumber: CUCUMBER_FILTER_TAGS="@Notification" ./gradlew test --tests "*CucumberTestRunner"
5. Manual E2E: restrictive Config:Permissions → notifications only for accessible entities
6. Parity: same user + Config:Permissions → same decision from endpoint and document sync

Decisions

• Approach: Replication-backend API — single source of truth for CASL + identity resolution
• Contract: aam-services sends bare Keycloak UUIDs (minimal, stable contract)
• Identity resolution: replication-backend resolves UUID → username/roles (Keycloak Admin API) + projects (CouchDB)
• Service auth: Basic Auth with shared CouchDB admin credentials
• Activation: PermissionCheckClient lives in common/, activates when replication-backend URL is configured — no separate feature flag. Permission checking is mandatory when notifications are enabled (required dependency).
• Fail-safe: skip notification on runtime check failure (don't leak data)
• Excluded: other module enforcement (can inject PermissionCheckClient later), ndb-core UI changes

Further Considerations

1. Performance at scale: user identity cache in replication-backend mitigates Keycloak API calls; batch endpoint handles many users in one HTTP call. For very high throughput, consider pre-warming cache on startup.
2. Keycloak client setup: need a client with view-users + view-realm realm-management roles for the admin API. Could reuse an existing service account or create a dedicated one.
3. Future reuse: the /permissions/check endpoint is generic — other services (or aam-services modules beyond notifications) can use it for any permission check by calling the same API.