Relevant source files

The following files were used as context for generating this wiki page: - [PLAN.md](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/PLAN.md) - [backend/src/fga/fgaClient.ts](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/backend/src/fga/fgaClient.ts) - [backend/src/modules/permissions/permissions.routes.ts](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/backend/src/modules/permissions/permissions.routes.ts) - [backend/src/modules/me/me.routes.ts](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/backend/src/modules/me/me.routes.ts) - [backend/src/middleware/authorizeTable.ts](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/backend/src/middleware/authorizeTable.ts) - [backend/src/modules/users/users.routes.ts](https://github.com/zaeeeeeem/MuteTaxes_Backend/blob/main/backend/src/modules/users/users.routes.ts)

# Module: Permissions & FGA The Permissions & FGA module provides a Relationship-Based Access Control (ReBAC) system using OpenFGA. It manages the lifecycle of authorization models, relationship tuples, and permission checks to control access to various "tables" (resources) within the application. The system integrates a Node.js backend with an OpenFGA server to enforce granular CRUD permissions based on user roles and direct associations. The module serves as the central authority for determining whether a user can create, read, update, or delete records in specific modules. It enables a "Permission Matrix" where administrators can toggle access for different roles, which then dynamically updates the user interface and protects backend API endpoints. Sources: [PLAN.md:3-8](), [backend/src/fga/fgaClient.ts:94-110]() ## Authorization Model & Schema The system uses a domain-specific language (DSL) to define relationships between users, roles, and tables. The authorization model is defined in `infra/openfga/model.fga` and contains three primary types: `user`, `role`, and `table`. ### Model Structure ```mermaid classDiagram class user { } class role { +member: user } class table { +creator: user | role#member +reader: user | role#member +updater: user | role#member +deleter: user | role#member +can_create: creator +can_read: reader or creator or updater or deleter +can_update: updater or creator +can_delete: deleter or creator } role "1" -- "*" user : member table "1" -- "*" user : direct access table "1" -- "*" role : access via member ``` *Note: The diagram illustrates the relationship-based hierarchy where `table` permissions are derived from assigned badges or role membership.* Sources: [PLAN.md:23-40](), [backend/src/fga/fgaClient.ts:25-30]() ## OpenFGA Client Integration The `fgaClient.ts` utility acts as a wrapper for the `@openfga/sdk`. It handles connection configuration, model initialization, and provides high-level functions for tuple management and permission verification. ### Key Integration Functions | Function | Purpose | Logic | | :--- | :--- | :--- | | `checkPermission` | Validates user access | Checks if `user:userId` has `can_action` on `table:tableSlug` | | `writeTuples` | Atomic updates | Batch writes or deletes relationship tuples with `Ignore` flags for duplicates/missing | | `assignRoleToUser` | Role membership | Writes a tuple: `user:userId` is `member` of `role:roleName` | | `grantCrudBadgeToRole`| Resource access | Connects `role:roleName#member` to a specific table relation (e.g., `reader`) | Sources: [backend/src/fga/fgaClient.ts:94-108](), [backend/src/fga/fgaClient.ts:162-184](), [backend/src/fga/fgaClient.ts:205-215]() ### Model Auto-Resolution The client includes logic to ensure a valid authorization model exists. If the `OPENFGA_AUTH_MODEL_ID` is not provided or invalid, it reads the local `.fga` file, transforms it to JSON using `@openfga/syntax-transformer`, and uploads it to the OpenFGA store. Sources: [backend/src/fga/fgaClient.ts:33-87]() ## Permission Matrix & Admin API The `permissions.routes.ts` module provides endpoints for Super Admins to view and modify the global permission state. ### Matrix Retrieval Flow The `/matrix` endpoint aggregates data from the Postgres database (roles and tables) and performs parallelized OpenFGA checks to build a comprehensive access grid. ```mermaid sequenceDiagram participant Admin as Super Admin participant API as Permissions API participant DB as Prisma/Postgres participant FGA as OpenFGA Server Admin->>API: GET /permissions/matrix API->>DB: findMany (Roles & Tables) DB-->>API: roles[], tables[] loop Every Role x Table API->>FGA: check(creator, reader, updater, deleter) FGA-->>API: allowed (true/false) end API-->>Admin: { roles, tables, matrix } ``` *Note: This sequence illustrates the heavy-read operation used to populate the administrative UI grid.* Sources: [backend/src/modules/permissions/permissions.routes.ts:11-40]() ### Updating Permissions Permissions are updated via the `/update` or `/up` endpoints. These endpoints convert boolean flags from the request body into OpenFGA tuple operations. - **Allowed: true** → Added to the `writes` array. - **Allowed: false** → Added to the `deletes` array. Sources: [backend/src/modules/permissions/permissions.routes.ts:43-85]() ## Middleware & Access Enforcement Access control is enforced at the route level using specialized middleware and "Visualization Endpoints" that provide the frontend with the current user's effective permissions. ### Authorization Middleware The `authorizeTable` middleware prevents unauthorized access to protected resource routes by performing a `checkPermission` call before reaching the controller. ```typescript // backend/src/middleware/authorizeTable.ts:6-18 export const authorizeTable = (action: FgaAction, tableSlug: string) => { return async (req: AuthenticatedRequest, res: Response, next: NextFunction) => { if (!req.user) return res.status(401).json({ error: "Unauthorized" }); const allowed = await checkPermission(req.user.id, tableSlug, action); if (!allowed) return res.status(403).json({ error: "Forbidden" }); return next(); }; }; ``` ### Visualization Endpoints (`/me`) - `GET /me/allowed-tables`: Returns a list of all tables where the user has at least `can_read` permission. Used to populate the sidebar. - `GET /me/table-permissions`: Returns a detailed CRUD boolean object for a specific table. Used to show/hide UI action buttons. Sources: [backend/src/modules/me/me.routes.ts:11-57](), [backend/src/middleware/authorizeTable.ts:6-18]() ## Data Relationships Summary | Entity | OpenFGA Object | Relation | Subject | | :--- | :--- | :--- | :--- | | Role Assignment | `role:` | `member` | `user:` | | Role Permission | `table:`| `reader`, `creator`, etc. | `role:#member` | | Direct User Access | `table:`| `reader`, `creator`, etc. | `user:` | Sources: [PLAN.md:85-110](), [backend/src/fga/fgaClient.ts:141-159]() ## Conclusion The Permissions & FGA module centralizes authorization logic, moving it out of the application code and into a relationship-based model. By combining OpenFGA's tuple-based checks with Express middleware, the system ensures that both the user interface and the underlying API endpoints consistently respect the configured permission matrix. This architecture allows for real-time permission updates without requiring code changes or database migrations.