Feat/rbac v1 #2092

Marfuen · 2026-02-02T22:29:16Z

What does this PR do?

Fixes #XXXX (GitHub issue number)
Fixes COMP-XXXX (Linear issue number - should be visible at the bottom of the GitHub issue description)

Visual Demo (For contributors especially)

A visual demonstration is strongly recommended, for both the original and new change (video / image - any one).

Video Demo (if applicable):

Show screen recordings of the issue or feature.
Demonstrate how to reproduce the issue, the behavior before and after the change.

Image Demo (if applicable):

Add side-by-side screenshots of the original and updated change.
Highlight any significant change(s).

Mandatory Tasks (DO NOT REMOVE)

I have self-reviewed the code (A decent size PR without self-review might be rejected).
I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. If N/A, write N/A here and check the checkbox.
I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

Are there environment variables that should be set?
What are the minimal test data to have?
What is expected (happy path) to have (input and output)?
Any other important info that could help to test that PR

Checklist

I haven't read the contributing guide
My code doesn't follow the style guidelines of this project
I haven't commented my code, particularly in hard-to-understand areas
I haven't checked if my changes generate no new warnings

- Update permissions.ts to extend defaultStatements from better-auth - Add GRC resources: control, evidence, policy, risk, vendor, task, framework, audit, finding, questionnaire, integration - Add program_manager role with full GRC access but no member management - Update owner/admin roles to extend ownerAc/adminAc from better-auth - Update auditor role with read + export permissions - Keep employee/contractor roles minimal with assignment-based access - Add ROLE_HIERARCHY, RESTRICTED_ROLES, PRIVILEGED_ROLES exports - Add placeholder for dynamicAccessControl in auth.ts (Sprint 2) Part of ENG-138: Complete Permission System Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Create PermissionGuard that calls better-auth's hasPermission API - Add fallback role-based check when better-auth is unavailable - Create @RequirePermission decorator for route-level permission checks - Create @RequirePermissions decorator for multi-resource permissions - Export GRCResource and GRCAction types for type safety - Add program_manager to Role enum in database schema - Update AuthModule to export PermissionGuard The guard: - Validates permissions via better-auth's hasPermission endpoint - Falls back to role-based check if API unavailable - Logs warnings for API key bypass (TODO: add API key scopes) - Provides static isRestrictedRole() helper for assignment filtering Part of ENG-138: Complete Permission System Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Update portal permissions.ts to match app version - Fix security issue where employee/contractor had excessive permissions - Add program_manager role to portal - Extend defaultStatements from better-auth - Add RESTRICTED_ROLES and PRIVILEGED_ROLES exports BREAKING CHANGE: Employee and contractor roles in portal now have restricted permissions matching the app. Previously they had member management and organization update permissions. Part of ENG-138: Complete Permission System Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add comprehensive tests for PermissionGuard covering: - Permission bypass when no permissions required - API key bypass behavior - Role-based access for privileged vs restricted roles - Fallback behavior when better-auth API unavailable - isRestrictedRole static method for all role types Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Migrate all API controllers to use the new better-auth permission system: - findings.controller.ts: finding create/update/delete permissions - task-management.controller.ts: task CRUD + assign permissions - people.controller.ts: member delete permission for removeHost - evidence-export.controller.ts: evidence export permission Also fix TypeScript errors in permission.guard.spec.ts for fetch mocking. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Implement assignment filtering to restrict employees/contractors to only see resources they are assigned to: - Add memberId to AuthContext for assignment checking - Create assignment-filter utility with filter builders and access checkers - Update tasks controller/service with assignment filtering on GET endpoints - Update risks controller/service with assignment filtering on GET endpoints - Add PermissionGuard and @RequirePermission to tasks and risks endpoints Employees/contractors now only see: - Tasks where they are the assignee - Risks where they are the assignee Privileged roles (owner, admin, program_manager, auditor) see all resources. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Allow admins to control which departments can see specific policies: Schema changes: - Add PolicyVisibility enum (ALL, DEPARTMENT) - Add visibility and visibleToDepartments fields to Policy model API changes: - Add memberDepartment to AuthContext for visibility filtering - Create department-visibility utility with filter builders - Update policies controller to filter by visibility for restricted roles - Update policies service to accept visibility filter Policies can now be: - Visible to ALL (default) - everyone in the organization sees them - Visible to specific DEPARTMENTS only - only members in those departments see them Privileged roles (owner, admin, program_manager, auditor) see all policies regardless of visibility settings. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Move auth server to API, app now uses proxy to forward auth requests - Remove localStorage token storage (XSS prevention) - Add rate limiting to auth proxy (60/min general, 10/min sensitive) - Add redirect URL validation to prevent open redirects - Add AUTH_SECRET validation at startup - Make all debug logging conditional on NODE_ENV - Simplify root page routing (no activeOrganizationId dependency) - Use URL-based RBAC with direct DB member lookup Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add @comp/auth package with centralized permissions and role definitions - Update API auth module to integrate with better-auth server - Add 403 responses to policy and risk endpoints for Swagger - Add assignment filter and department visibility utilities with tests - Sync permissions across app and portal - Update tsconfig and nest-cli for proper module resolution Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add dynamicAccessControl config to organization plugin - Add OrganizationRole table for storing custom roles - Configure maximum 20 roles per organization - Add schema mapping for better-auth role table Resolves: ENG-145 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add roles module with CRUD endpoints for custom roles - Implement privilege escalation prevention - Add permission validation against valid resources/actions - Protect built-in roles (owner, admin, auditor, employee, contractor) - Add OrganizationRole table migration - Limit to 20 custom roles per organization - Require ac:create/read/update/delete permissions for role management Implements: ENG-146 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Update roles service to accept array of roles instead of single role - Add getCombinedPermissions to merge permissions from all user roles - Update controller to pass full userRoles array - Users with multiple roles now get combined permissions for validation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add explicit jwks configuration with rotationInterval to prevent better-auth from creating new JWKS keys on each request. Without this, all existing JWTs become invalid when the API restarts because new signing keys are generated. - Set rotationInterval to 30 days for monthly key rotation - Set gracePeriod to 7 days so old keys remain valid after rotation Fixes: Session persistence across API restarts References: - better-auth/better-auth#6215 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add 18 tests for RolesService covering CRUD operations - Add 9 tests for RolesController - Test permission validation and privilege escalation prevention - Test multiple roles support for privilege checking - Test edge cases (duplicate names, max roles limit, reserved names) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Update .cursorrules with testing requirements and conventions - Add apps/api/CLAUDE.md with API-specific development guidelines - Document when to write tests, how to run them, and test patterns - Include RBAC system documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Remove API-specific testing rules from root .cursorrules - Create apps/api/.cursorrules with API testing requirements - Keep root .cursorrules focused on commit message conventions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Ensures that users cannot escalate privileges when updating role permissions, not just when creating roles. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add roles settings pages (list, create, edit) with permission matrix - Add "Select all" feature to quickly set all permissions - Integrate custom roles into member management UI: - Role filter dropdown shows all roles dynamically - Invite modal supports custom role selection - Edit member role supports custom roles - Allow normal spelling for role names (spaces, capitalization) - Add loading skeletons with proper PageLayout wrappers - Add comprehensive tests for RolesTable, RoleForm, PermissionMatrix Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cursor · 2026-02-02T22:29:21Z

PR Summary

High Risk
High risk because it changes authentication/authorization plumbing (Better Auth server integration, new PermissionGuard, updated auth context) and applies new permission checks across many API endpoints, which can easily cause unintended access regressions.

Overview
Introduces a Better Auth–backed RBAC layer in the API: adds PermissionGuard + @RequirePermission decorators, wires Better Auth’s NestJS module into AuthModule, and tightens many controllers to require explicit permissions (with API keys currently bypassing checks).

Adds a new roles module with CRUD endpoints for custom roles stored in organization_role, including validation of resources/actions, role limits, and privilege-escalation prevention (cannot grant permissions the caller doesn’t have; extra guard for organization:delete).

Expands auth context to include memberId/memberDepartment, uses these for restricted-role filtering (assignment-based risk listing/access and department-based policy visibility + 403s), adds startup JWKS cleanup for secret rotations, and updates notification flows to skip platform admins and pass organizationId into unsubscribe checks (with new unit tests).

^{Written by Cursor Bugbot for commit 3a9e9f1. This will update automatically on new commits. Configure here.}

vercel · 2026-02-02T22:29:21Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Error		Feb 3, 2026 8:39pm
portal	Ready	Preview, Comment	Feb 3, 2026 8:39pm

apps/api/src/roles/roles.controller.ts

apps/api/src/roles/roles.service.ts

cursor · 2026-02-02T22:42:53Z

apps/api/src/auth/permission.guard.ts

+    this.betterAuthUrl =
+      this.configService.get<string>('BETTER_AUTH_URL') ||
+      process.env.BETTER_AUTH_URL ||
+      '';


PermissionGuard ignores AUTH_BASE_URL config setting

Medium Severity

The PermissionGuard reads BETTER_AUTH_URL directly instead of using the betterAuth config namespace like HybridAuthGuard does. The better-auth.config.ts prioritizes AUTH_BASE_URL over BETTER_AUTH_URL, but PermissionGuard ignores this. If only AUTH_BASE_URL is configured, permission checks will silently fall back to basic role-based checks because betterAuthUrl will be empty.

apps/api/src/utils/assignment-filter.ts

cursor · 2026-02-03T18:57:02Z

apps/api/src/questionnaire/questionnaire.controller.ts

  }

  @Post('parse/upload/token')
+  @UseGuards() // Override class-level guards — this endpoint uses token-based auth


Empty UseGuards doesn't override class-level guards

High Severity

The @UseGuards() decorator with no arguments on the /parse/upload/token endpoint does not override the class-level @UseGuards(HybridAuthGuard, PermissionGuard). In NestJS, method-level guards are additive, not replacing. The endpoint is intended for token-based public access from the trust portal, but will still require JWT/API key authentication, breaking the trust portal questionnaire upload feature.

apps/api/src/roles/roles.service.ts

apps/api/src/auth/permission.guard.ts

cursor · 2026-02-03T18:57:02Z

apps/api/src/auth/permission.guard.ts

+
+    // Check if all roles are restricted
+    return roles.every((role) => RESTRICTED_ROLES.includes(role));
+  }


Static isRestrictedRole duplicates existing utility function

Medium Severity

PermissionGuard.isRestrictedRole duplicates the isRestrictedRole function already exported from apps/api/src/utils/assignment-filter.ts. Both implementations have identical logic. The guard should import and use the existing utility function instead.

cursor · 2026-02-03T18:57:02Z

apps/api/src/auth/auth-context.decorator.ts

+    const request = ctx.switchToHttp().getRequest<AuthenticatedRequest>();
+    return request.memberId;
+  },
+);


Unused MemberId decorator export

Low Severity

The MemberId decorator is exported but never imported or used anywhere in the codebase. Controllers access memberId via the AuthContext decorator instead. This is dead code.

cursor · 2026-02-03T18:57:02Z

apps/api/src/auth/require-permission.decorator.ts

+  | 'approve'
+  | 'assess'
+  | 'complete'
+  | 'respond';


Unused RequirePermissions decorator and type exports

Low Severity

RequirePermissions (plural), GRCResource, and GRCAction are exported but never imported anywhere. Only RequirePermission (singular) is used across controllers. These are dead code.

…rotection - Add functions to resolve user permissions based on roles and organization - Implement route permission checks to guard access to various app sections - Introduce new layout components for route protection across multiple pages - Update existing components to utilize the new permissions system for access control

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-03T20:34:28Z

apps/api/src/roles/roles.service.ts

+          );
+        }
+      }
+    }


Missing validation for permission value types causes crash

Medium Severity

The validatePermissions method iterates over permission values with for (const action of actions) without checking that actions is actually an array. The DTO only validates that permissions is an object via @IsObject(), not that nested values are arrays. If a client sends { "permissions": { "control": null } }, the iteration throws a TypeError (null is not iterable), causing a 500 error instead of a proper 400 validation error.

Additional Locations (1)

apps/api/src/roles/dto/create-role.dto.ts#L27-L30

cursor · 2026-02-03T20:34:28Z

apps/api/src/roles/roles.service.ts

+  integration: ['create', 'read', 'update', 'delete'],
+  app: ['read'],
+  portal: ['read', 'update'],
+};


Duplicated permission definitions across auth and roles

Medium Severity

VALID_RESOURCES in roles.service.ts duplicates the permission statement object defined in auth.server.ts. Both define the same resources and actions (control, evidence, policy, risk, etc.). If permissions change, both files must be updated separately, risking inconsistency.

Marfuen and others added 19 commits February 2, 2026 12:19

test(rbac): add privilege escalation test for role updates

1209d32

Ensures that users cannot escalate privileges when updating role permissions, not just when creating roles. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore(docs): add API endpoints for managing custom roles

eaf197e

mintlify bot deployed to staging - packages/docs February 2, 2026 22:29 View deployment

vercel bot temporarily deployed to Preview – app February 2, 2026 22:36 Inactive

vercel bot temporarily deployed to Preview – portal February 2, 2026 22:36 Inactive

mintlify bot deployed to staging - packages/docs February 2, 2026 22:37 View deployment

cursor bot reviewed Feb 2, 2026

View reviewed changes

chore(auth): implement cleanup of stale JWKS records on secret change

c59d04f

mintlify bot deployed to staging - packages/docs February 3, 2026 18:51 View deployment

vercel bot had a problem deploying to Preview – app February 3, 2026 18:51 Failure

vercel bot deployed to Preview – portal February 3, 2026 18:52 View deployment

cursor bot reviewed Feb 3, 2026

View reviewed changes

vercel bot had a problem deploying to Preview – app February 3, 2026 20:25 Failure

cursor bot reviewed Feb 3, 2026

View reviewed changes

vercel bot deployed to Preview – portal February 3, 2026 20:40 View deployment

Feat/rbac v1 #2092

Are you sure you want to change the base?

Feat/rbac v1 #2092

Uh oh!

Conversation

Marfuen commented Feb 2, 2026

What does this PR do?

Visual Demo (For contributors especially)

Video Demo (if applicable):

Image Demo (if applicable):

Mandatory Tasks (DO NOT REMOVE)

How should this be tested?

Checklist

Uh oh!

cursor bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Feb 2, 2026

Choose a reason for hiding this comment

PermissionGuard ignores AUTH_BASE_URL config setting

Uh oh!

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Empty UseGuards doesn't override class-level guards

Uh oh!

Uh oh!

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Static isRestrictedRole duplicates existing utility function

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Unused MemberId decorator export

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Unused RequirePermissions decorator and type exports

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Missing validation for permission value types causes crash

Uh oh!

cursor bot Feb 3, 2026

Choose a reason for hiding this comment

Duplicated permission definitions across auth and roles

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cursor bot commented Feb 2, 2026 •

edited

Loading

vercel bot commented Feb 2, 2026 •

edited

Loading

Static `isRestrictedRole` duplicates existing utility function

Unused `MemberId` decorator export

Unused `RequirePermissions` decorator and type exports