Authorization and RBAC matrix
Model summary
FinTrack uses a tenant-scoped hierarchy of application access levels from L1 to
L10. The level is linked to the authenticated application profile; it is not a
shared database login or a substitute for authentication.
Authorization is applied in layers:
- Identity: Supabase Auth establishes the signed-in user.
- Account context: the application resolves the user's tenant, access level, reporting relationship, and login-eligible status.
- Navigation: tenant and access-level rules determine which application routes are shown or opened.
- Data scope: row-level security and trusted database operations enforce tenant, reporting-tree, mapped-subtree, and record-level access.
- Elevated operations: trusted server operations revalidate the actor and reject requests outside the permitted tenant, role, or target hierarchy.
Navigation visibility is a usability control. It is not treated as the authoritative security boundary.
Default role matrix
Tenant administrators can customise the display names associated with the stable level codes. The labels below are the default business labels.
| Level | Default label | Default operational data scope | User administration | Additional privileged capability |
|---|---|---|---|---|
L1 | Telecaller | Self and explicitly assigned records | None | Standard operational functions permitted by route and data policy |
L2 | Senior Telecaller | Self and authorised reporting subtree | None | Standard operational functions permitted by route and data policy |
L3 | Branch Manager and Operations | Self and authorised reporting subtree | Can create or manage lower-level users within the same tenant | Selected operational settings are delegated only through recorded policy |
L4 | Franchise Owner | Self and authorised reporting subtree | Can create or manage lower-level users within the same tenant | Field-hierarchy ownership and delegated reporting functions |
L5 | Agent | Own reporting tree and any approved mapped subtree | Can create or manage lower-level users within the same tenant | Agent-group functions permitted by policy; no automatic tenant-wide access |
L6 | CTL and BDM | Own reporting tree and any approved mapped subtree | Can create or manage lower-level users within the same tenant | Corporate operational functions permitted by policy |
L7 | Sales Manager | Own reporting tree and any approved mapped subtree | Can create or manage lower-level users within the same tenant | Corporate operational functions permitted by policy |
L8 | Channel Lead | Own reporting tree and any approved mapped subtree | Can create lower-level users; bulk onboarding is permitted only for lower levels | Senior operational functions permitted by policy |
L9 | Channel Head | Tenant-wide operational visibility by default | Can manage levels L1 to L9; cannot create L10 | Can administer approved visibility mappings and access senior reports and controls |
L10 | Leadership | Tenant-wide operational visibility by default | Can manage levels L1 to L9; peer creation is not enabled | Can administer approved visibility mappings and access senior reports and controls |
Higher rank does not automatically replace the reporting chain. The recorded manager relationship remains authoritative, while additional operational visibility is granted through a separate, same-tenant mapping.
Capability rules
| Capability | Rule |
|---|---|
| Single-user creation | Available from L3 upward; enforcement limits the target below the creator, while L9 and L10 can manage any non-L10 level |
| Bulk user onboarding | Available only to L8, L9, and L10; enforcement limits targets below the uploader and rejects L10 targets |
| Reporting-tree access | A user receives the scope authorised by the recorded reporting relationships and applicable data policy |
| Additional visibility | An active mapping adds normal operational access to an approved same-tenant subtree without changing the reporting chain |
| Mapping administration | Restricted to L9 and L10; mappings cannot cross tenants |
| Menu and route restriction | A restriction cascades from a selected level to that level and every lower level; exact-level exceptions are configurable separately |
| Privileged server processing | Requires a valid authenticated actor and a fresh tenant, level, account-status, and target-scope check |
| Database access | Exposed application tables are protected by row-level security; policy evaluation remains the final data-access boundary |
Enforcement evidence
The review verified that:
- all ten application levels are represented in the current user directory;
- the live public application tables have row-level security enabled;
- the database contains active row-level policies for authenticated application access;
- tenant-wide default visibility is limited to the two leadership levels;
- non-leadership visibility follows reporting or approved mapped subtrees rather than automatically granting all lower-level tenant data;
- user creation, bulk onboarding, account status changes, visibility administration, and selected high-impact operations perform server-side hierarchy checks.
Enabling row-level security does not by itself prove every policy is correct. Policy logic and privileged operations remain in scope for periodic access-control testing.
Authorization decision algorithm
Protected operations evaluate the following predicates in order. Failure at any required predicate returns a denial without falling back to a broader UI role:
- Identity: the managed session is valid and resolves to the authenticated application profile.
- Account state: the profile remains active and login-eligible at the time of the request.
- Tenant: actor and target belong to the same authorised tenant unless an explicitly approved cross-tenant service operation is in scope.
- Capability: the actor's current level and assigned permissions include the operation class.
- Hierarchy or mapping: the target is a subordinate, owned record, assigned unit, or explicitly mapped visibility target according to the operation's rule.
- Object state: the requested transition is valid for the current task, policy, document, user, or finance state.
- Field scope: the operation changes only fields permitted for the actor and transition.
- Transaction: constraints and audit attribution commit with the business mutation.
Negative authorization test matrix
| Case | Enforced result |
|---|---|
| Valid session, wrong tenant | No target record is returned or mutated; the denial is recorded at the appropriate boundary |
| Valid tenant, peer or superior target outside permitted hierarchy | Management operation is denied even if the page route is manually invoked |
| Hidden menu, direct API request | Backend grants, policies, and operation checks remain authoritative and deny unauthorized access |
| Stale browser role after user downgrade or offboarding | Current server-side profile state prevails; the protected operation fails and session handling returns the user to an eligible state or login |
| Actor-supplied tenant or user identifier | The value is not accepted as identity proof and cannot expand the session-derived scope |
| Trusted operation called without a valid user or event context | Elevated processing is rejected before privileged credentials or transaction rights are used |
| Bulk target set containing one unauthorized object | The operation rejects the unauthorized target and does not silently process it outside the approved partial-success design |
| Policy or document transition missing required evidence | The state change is rejected even when the actor otherwise has the correct role |
Administrative safeguards
- Access levels and reporting assignments require approval through the organisation's joiner, mover, and leaver process.
- Visibility mappings require a documented business owner, purpose, and review date.
- Leadership and privileged role assignments enter the periodic access review.
- Route configuration and database policies are reviewed together after access model changes.
- Service credentials capable of bypassing row-level security remain inside trusted server execution and are absent from the browser and public documentation.
- Access-control tests include cross-tenant access, peer-level access, stale sessions, direct API calls, and attempts to act on a target outside the actor's scope.