Access Scope Service
Component Detail
Description
Determines the set of organization units a given user may read or write data for, based on their assignments and role. Used to scope all data queries — activity lists, contact lists, statistics — so coordinators only see data for their assigned chapter(s). Interacts with Supabase RLS policies at the server side and provides client-side filtering helpers.
access-scope-service
Summaries
The Access Scope Service is the platform's central privacy and data governance mechanism, ensuring that coordinators, administrators, and other roles can only see and interact with data that belongs to their assigned organizational unit or units. This is not merely a convenience feature — it is a compliance requirement for organizations managing sensitive member and activity data under Norwegian data protection standards. By automatically scoping activity lists, contact directories, and statistics to the correct chapters, the platform eliminates the risk of data leakage between chapters, reduces the administrative burden of manually filtering data, and provides auditable access boundaries that satisfy governance requirements. This directly supports the trust that national federations and local chapters place in the platform.
Access Scope Service is a high-complexity, shared service that spans both backend and shared execution contexts, integrating with unit-assignment-service, hierarchy-service, and rls-policy-manager. Its position at the intersection of identity, organizational structure, and data access makes it one of the highest-risk components in the system — defects here affect every data-facing feature. Delivery requires tight coordination with the Supabase RLS policy configuration (rls-policy-manager), as JWT claims payload structure must match RLS policy expectations exactly. Plan for dedicated security testing including cross-tenant isolation validation, role-based access boundary tests, and session refresh scenarios.
Any feature that queries activity, contact, or statistics data depends on this service for correct scoping, so it must be available and stable early in the integration phase. Cache invalidation (refreshAccessScope) must be tested under concurrent session scenarios.
AccessScopeService computes and enforces the set of organization_units a user may access, bridging unit_assignment data with Supabase Row Level Security. Its interface includes getAccessibleUnitIds(userId), isUnitAccessible(userId, unitId), getScopedQuery(baseQuery, userId), buildRlsClaimsPayload(userId), and refreshAccessScope(userId). It runs in both backend (server-side RLS enforcement) and shared (client-side filtering helpers) contexts — the shared execution context means the client-side helpers must not expose sensitive scope computation logic or raw assignment data. buildRlsClaimsPayload() constructs the JWT custom claims object that Supabase RLS policies evaluate; the exact claim keys and structure must be agreed upon with the rls-policy-manager configuration.
getScopedQuery() provides a query modifier pattern — accept a base Supabase query builder and append .in('unit_id', accessibleUnitIds) or equivalent. Caching getAccessibleUnitIds() results per user session is critical for performance; invalidate on assignment change events emitted by unit-assignment-service. For users with hierarchy-level access (e.g., regional coordinators), accessible unit IDs must include all descendants via hierarchy-service.getDescendants().
Responsibilities
- Compute accessible unit IDs for the current user
- Provide scoped query helpers for features that need unit-filtered data
- Validate that a given unit is within the user's access scope
- Integrate with Supabase RLS policies via JWT claims
Interfaces
getAccessibleUnitIds(userId)
isUnitAccessible(userId, unitId)
getScopedQuery(baseQuery, userId)
buildRlsClaimsPayload(userId)
refreshAccessScope(userId)
Relationships
Dependencies (3)
Components this component depends on
Related Data Entities (4)
Data entities managed by this component