Feat/rbac v1

apps/api/.cursorrules

@@ -0,0 +1,80 @@
+# API Development Rules
+
+## Testing Requirements
+
+**Every new feature MUST include tests.** This is mandatory, not optional.
+
+### When to Write Tests
+
+1. **New features**: Every new service, controller, or significant function MUST have accompanying unit tests
+2. **Bug fixes**: Add a test that reproduces the bug before fixing it
+3. **Refactoring**: Ensure existing tests pass; add tests if coverage is lacking
+
+### When to Run Tests
+
+Run tests after significant changes:
+
+```bash
+# Run tests for a specific module
+npx jest src/<module-name> --passWithNoTests
+
+# Run all API tests
+npx turbo run test --filter=@comp/api
+
+# Run tests in watch mode during development
+npx jest --watch
+```
+
+### Test File Conventions
+
+- Place test files next to the source file: `foo.service.ts` → `foo.service.spec.ts`
+- Use Jest and NestJS testing utilities
+- Mock external dependencies (database, external APIs)
+- Test both success and error cases
+
+### Minimum Test Coverage
+
+- **Services**: Test all public methods, including error handling
+- **Controllers**: Test endpoint routing and parameter passing
+- **Guards**: Test authorization logic
+- **Utils**: Test edge cases and error conditions
+
+### Example Test Structure
+
+```typescript
+describe('MyService', () => {
+  describe('myMethod', () => {
+    it('should handle success case', async () => { ... });
+    it('should throw on invalid input', async () => { ... });
+    it('should handle edge case X', async () => { ... });
+  });
+});
+```
+
+## Development Workflow
+
+1. **Before coding**: Read existing code patterns in the module
+2. **During coding**: Follow established patterns, add types
+3. **After significant changes**:
+   - Run type-check: `npx turbo run typecheck --filter=@comp/api`
+   - Run tests: `npx jest src/<module>`
+4. **Before committing**: Ensure all tests pass
+
+## Code Style
+
+### Authentication & Authorization
+
+- Use `@UseGuards(HybridAuthGuard, PermissionGuard)` for protected endpoints
+- Use `@RequirePermission('resource', 'action')` decorator for RBAC
+- Access auth context via `@AuthContext()` decorator
+- Access organization ID via `@OrganizationId()` decorator
+
+### Error Handling
+
+- Use NestJS exceptions: `BadRequestException`, `NotFoundException`, `ForbiddenException`
+- Provide clear, actionable error messages
+
+### Database Access
+
+- Always scope queries by `organizationId` for multi-tenancy
+- Use transactions for operations that modify multiple records

apps/api/CLAUDE.md

@@ -0,0 +1,140 @@
+# API Development Guidelines
+
+This document provides guidelines for AI assistants (Claude, Cursor, etc.) when working on the API codebase.
+
+## Project Structure
+
+```
+apps/api/src/
+├── auth/           # Authentication (better-auth, guards, decorators)
+├── roles/          # Custom roles CRUD API
+├── <module>/       # Feature modules (controller, service, DTOs)
+└── utils/          # Shared utilities
+```
+
+## Testing Requirements
+
+### Mandatory Testing
+
+**Every new feature MUST include tests.** Before marking a task as complete:
+
+1. Write unit tests for new services and controllers
+2. Run the tests to verify they pass
+3. Commit tests alongside the feature code
+
+### Running Tests
+
+```bash
+# Run tests for a specific module (from apps/api directory)
+npx jest src/<module-name> --passWithNoTests
+
+# Run tests for changed files only
+npx jest --onlyChanged
+
+# Run all API tests (from repo root)
+npx turbo run test --filter=@comp/api
+
+# Type-check before committing
+npx turbo run typecheck --filter=@comp/api
+```
+
+### Test Patterns
+
+Follow existing test patterns in the codebase:
+
+```typescript
+// Mock external dependencies
+jest.mock('@trycompai/db', () => ({
+  db: {
+    someTable: {
+      findFirst: jest.fn(),
+      create: jest.fn(),
+      // ...
+    },
+  },
+}));
+
+// Mock ESM modules if needed (e.g., jose)
+jest.mock('jose', () => ({
+  createRemoteJWKSet: jest.fn(),
+  jwtVerify: jest.fn(),
+}));
+
+// Override guards in controller tests
+const module = await Test.createTestingModule({
+  controllers: [MyController],
+  providers: [{ provide: MyService, useValue: mockService }],
+})
+  .overrideGuard(HybridAuthGuard)
+  .useValue({ canActivate: () => true })
+  .compile();
+```
+
+### What to Test
+
+| Component | Test Coverage |
+|-----------|---------------|
+| Services | All public methods, validation logic, error handling |
+| Controllers | Parameter passing to services, response mapping |
+| Guards | Authorization decisions, edge cases |
+| DTOs | Validation decorators (via e2e or integration tests) |
+| Utils | All functions, edge cases, error conditions |
+
+## Code Style
+
+### Authentication & Authorization
+
+- Use `@UseGuards(HybridAuthGuard, PermissionGuard)` for protected endpoints
+- Use `@RequirePermission('resource', 'action')` decorator for RBAC
+- Access auth context via `@AuthContext()` decorator
+- Access organization ID via `@OrganizationId()` decorator
+
+### Error Handling
+
+- Use NestJS exceptions: `BadRequestException`, `NotFoundException`, `ForbiddenException`
+- Provide clear, actionable error messages
+- Don't expose internal details in error responses
+
+### Database Access
+
+- Use Prisma via `@trycompai/db`
+- Always scope queries by `organizationId` for multi-tenancy
+- Use transactions for operations that modify multiple records
+
+## Development Workflow
+
+1. **Before coding**: Read existing code patterns in the module
+2. **During coding**: Follow established patterns, add types
+3. **After coding**:
+   - Run `npx turbo run typecheck --filter=@comp/api`
+   - Write and run tests: `npx jest src/<module>`
+   - Commit with conventional commit message
+
+## Common Commands
+
+```bash
+# Start API in development
+npx turbo run dev --filter=@comp/api
+
+# Type-check
+npx turbo run typecheck --filter=@comp/api
+
+# Run specific test file
+npx jest src/roles/roles.service.spec.ts
+
+# Generate Prisma client after schema changes
+cd packages/db && npx prisma generate
+```
+
+## RBAC System
+
+The API uses a hybrid RBAC system:
+
+- **Built-in roles**: owner, admin, auditor, employee, contractor
+- **Custom roles**: Stored in `organization_role` table
+- **Permissions**: `resource:action` format (e.g., `control:read`)
+- **Multiple roles**: Users can have multiple roles (comma-separated in `member.role`)
+
+When checking permissions:
+- Use `@RequirePermission('resource', 'action')` for endpoint protection
+- For privilege escalation checks, combine permissions from all user roles

apps/api/nest-cli.json

@@ -2,6 +2,7 @@
   "$schema": "https://json.schemastore.org/nest-cli",
   "collection": "@nestjs/schematics",
   "sourceRoot": "src",
+  "entryFile": "src/main",
   "compilerOptions": {
     "deleteOutDir": true
   }

apps/api/package.json

@@ -24,6 +24,7 @@
     "@prisma/client": "6.18.0",
     "@prisma/instrumentation": "^6.13.0",
     "@react-email/components": "^0.0.41",
+    "@thallesp/nestjs-better-auth": "^2.2.5",
     "@trigger.dev/build": "4.0.6",
     "@trigger.dev/sdk": "4.0.6",
     "@trycompai/db": "1.3.21",

apps/api/src/app.module.ts

@@ -34,6 +34,7 @@ import { BrowserbaseModule } from './browserbase/browserbase.module';
 import { TaskManagementModule } from './task-management/task-management.module';
 import { AssistantChatModule } from './assistant-chat/assistant-chat.module';
 import { TrainingModule } from './training/training.module';
+import { RolesModule } from './roles/roles.module';
 
 @Module({
   imports: [
@@ -53,6 +54,7 @@ import { TrainingModule } from './training/training.module';
       },
     ]),
     AuthModule,
+    RolesModule,
     OrganizationModule,
     PeopleModule,
     RisksModule,

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

@@ -9,8 +9,16 @@ export const AuthContext = createParamDecorator(
   (data: unknown, ctx: ExecutionContext): AuthContextType => {
     const request = ctx.switchToHttp().getRequest<AuthenticatedRequest>();
 
-    const { organizationId, authType, isApiKey, userId, userEmail, userRoles } =
-      request;
+    const {
+      organizationId,
+      authType,
+      isApiKey,
+      userId,
+      userEmail,
+      userRoles,
+      memberId,
+      memberDepartment,
+    } = request;
 
     if (!organizationId || !authType) {
       throw new Error(
@@ -25,6 +33,8 @@ export const AuthContext = createParamDecorator(
       userId,
       userEmail,
       userRoles,
+      memberId,
+      memberDepartment,
     };
   },
 );
@@ -69,6 +79,16 @@ export const UserId = createParamDecorator(
   },
 );
 
+/**
+ * Parameter decorator to extract the member ID (only available for session auth)
+ */
+export const MemberId = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): string | undefined => {
+    const request = ctx.switchToHttp().getRequest<AuthenticatedRequest>();
+    return request.memberId;
+  },
+);
+
 /**
  * Parameter decorator to check if the request is authenticated via API key
  */

apps/api/src/auth/auth.module.ts

@@ -1,11 +1,35 @@
 import { Module } from '@nestjs/common';
+import { AuthModule as BetterAuthModule } from '@thallesp/nestjs-better-auth';
+import { auth } from './auth.server';
 import { ApiKeyGuard } from './api-key.guard';
 import { ApiKeyService } from './api-key.service';
 import { HybridAuthGuard } from './hybrid-auth.guard';
 import { InternalTokenGuard } from './internal-token.guard';
+import { PermissionGuard } from './permission.guard';
 
 @Module({
-  providers: [ApiKeyService, ApiKeyGuard, HybridAuthGuard, InternalTokenGuard],
-  exports: [ApiKeyService, ApiKeyGuard, HybridAuthGuard, InternalTokenGuard],
+  imports: [
+    // Better Auth NestJS integration - handles /api/auth/* routes
+    BetterAuthModule.forRoot({
+      auth,
+      // Don't register global auth guard - we use HybridAuthGuard
+      disableGlobalAuthGuard: true,
+    }),
+  ],
+  providers: [
+    ApiKeyService,
+    ApiKeyGuard,
+    HybridAuthGuard,
+    InternalTokenGuard,
+    PermissionGuard,
+  ],
+  exports: [
+    ApiKeyService,
+    ApiKeyGuard,
+    HybridAuthGuard,
+    InternalTokenGuard,
+    PermissionGuard,
+    BetterAuthModule,
+  ],
 })
 export class AuthModule {}