# Common Guards and Decorators

This directory contains shared guards and decorators for workspace-based permission management in the Mosaic Stack API.

## Overview

The permission system provides:
- **Workspace isolation** via Row-Level Security (RLS)
- **Role-based access control** (RBAC) using workspace member roles
- **Declarative permission requirements** using decorators

## Guards

### AuthGuard

Located in `../auth/guards/auth.guard.ts`

Verifies user authentication and attaches user data to the request.

**Sets on request:**
- `request.user` - Authenticated user object
- `request.session` - User session data

### WorkspaceGuard

Validates workspace access and sets up RLS context.

**Responsibilities:**
1. Extracts workspace ID from request (header, param, or body)
2. Verifies user is a member of the workspace
3. Sets the current user context for RLS policies
4. Attaches workspace context to the request

**Sets on request:**
- `request.workspace.id` - Validated workspace ID
- `request.user.workspaceId` - Workspace ID (for backward compatibility)

**Workspace ID Sources (in priority order):**
1. `X-Workspace-Id` header
2. `:workspaceId` URL parameter
3. `workspaceId` in request body

**Example:**
```typescript
@Controller('tasks')
@UseGuards(AuthGuard, WorkspaceGuard)
export class TasksController {
  @Get()
  async getTasks(@Workspace() workspaceId: string) {
    // workspaceId is validated and RLS context is set
  }
}
```

### PermissionGuard

Enforces role-based access control using workspace member roles.

**Responsibilities:**
1. Reads required permission from `@RequirePermission()` decorator
2. Fetches user's role in the workspace
3. Checks if role satisfies the required permission
4. Attaches role to request for convenience

**Sets on request:**
- `request.user.workspaceRole` - User's role in the workspace

**Must be used after AuthGuard and WorkspaceGuard.**

**Example:**
```typescript
@Controller('admin')
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
export class AdminController {
  @RequirePermission(Permission.WORKSPACE_ADMIN)
  @Delete('data')
  async deleteData() {
    // Only ADMIN or OWNER can execute
  }
}
```

## Decorators

### @RequirePermission(permission: Permission)

Specifies the minimum permission level required for a route.

**Permission Levels:**

| Permission | Allowed Roles | Use Case |
|------------|--------------|----------|
| `WORKSPACE_OWNER` | OWNER | Critical operations (delete workspace, transfer ownership) |
| `WORKSPACE_ADMIN` | OWNER, ADMIN | Administrative functions (manage members, settings) |
| `WORKSPACE_MEMBER` | OWNER, ADMIN, MEMBER | Standard operations (create/edit content) |
| `WORKSPACE_ANY` | All roles including GUEST | Read-only or basic access |

**Example:**
```typescript
@RequirePermission(Permission.WORKSPACE_ADMIN)
@Post('invite')
async inviteMember(@Body() inviteDto: InviteDto) {
  // Only admins can invite members
}
```

### @Workspace()

Parameter decorator to extract the validated workspace ID.

**Example:**
```typescript
@Get()
async getTasks(@Workspace() workspaceId: string) {
  // workspaceId is guaranteed to be valid
}
```

### @WorkspaceContext()

Parameter decorator to extract the full workspace context.

**Example:**
```typescript
@Get()
async getTasks(@WorkspaceContext() workspace: { id: string }) {
  console.log(workspace.id);
}
```

### @CurrentUser()

Located in `../auth/decorators/current-user.decorator.ts`

Extracts the authenticated user from the request.

**Example:**
```typescript
@Post()
async create(@CurrentUser() user: any, @Body() dto: CreateDto) {
  // user contains authenticated user data
}
```

## Usage Patterns

### Basic Controller Setup

```typescript
import { Controller, Get, Post, UseGuards } from "@nestjs/common";
import { AuthGuard } from "../auth/guards/auth.guard";
import { WorkspaceGuard, PermissionGuard } from "../common/guards";
import { Workspace, Permission, RequirePermission } from "../common/decorators";
import { CurrentUser } from "../auth/decorators/current-user.decorator";

@Controller('resources')
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
export class ResourcesController {
  @Get()
  @RequirePermission(Permission.WORKSPACE_ANY)
  async list(@Workspace() workspaceId: string) {
    // All members can list
  }

  @Post()
  @RequirePermission(Permission.WORKSPACE_MEMBER)
  async create(
    @Workspace() workspaceId: string,
    @CurrentUser() user: any,
    @Body() dto: CreateDto
  ) {
    // Members and above can create
  }

  @Delete(':id')
  @RequirePermission(Permission.WORKSPACE_ADMIN)
  async delete(@Param('id') id: string) {
    // Only admins can delete
  }
}
```

### Mixed Permissions

Different endpoints can have different permission requirements:

```typescript
@Controller('projects')
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
export class ProjectsController {
  @Get()
  @RequirePermission(Permission.WORKSPACE_ANY)
  async list() { /* Anyone can view */ }

  @Post()
  @RequirePermission(Permission.WORKSPACE_MEMBER)
  async create() { /* Members can create */ }

  @Patch('settings')
  @RequirePermission(Permission.WORKSPACE_ADMIN)
  async updateSettings() { /* Only admins */ }

  @Delete()
  @RequirePermission(Permission.WORKSPACE_OWNER)
  async deleteProject() { /* Only owner */ }
}
```

### Workspace ID in Request

The workspace ID can be provided in multiple ways:

**Via Header (Recommended for SPAs):**
```typescript
// Frontend
fetch('/api/tasks', {
  headers: {
    'Authorization': 'Bearer <token>',
    'X-Workspace-Id': 'workspace-uuid',
  }
})
```

**Via URL Parameter:**
```typescript
@Get(':workspaceId/tasks')
async getTasks(@Param('workspaceId') workspaceId: string) {
  // workspaceId extracted from URL
}
```

**Via Request Body:**
```typescript
@Post()
async create(@Body() dto: { workspaceId: string; name: string }) {
  // workspaceId extracted from body
}
```

## Row-Level Security (RLS)

When `WorkspaceGuard` is applied, it automatically:
1. Calls `setCurrentUser(userId)` to set the RLS context
2. All subsequent database queries are automatically filtered by RLS policies
3. Users can only access data in workspaces they're members of

**See:** `docs/design/multi-tenant-rls.md` for full RLS documentation.

## Testing

Tests are provided for both guards:
- `workspace.guard.spec.ts` - WorkspaceGuard tests
- `permission.guard.spec.ts` - PermissionGuard tests

**Run tests:**
```bash
npm test -- workspace.guard.spec
npm test -- permission.guard.spec
```

## Error Handling

### WorkspaceGuard Errors

- `ForbiddenException("User not authenticated")` - No authenticated user
- `BadRequestException("Workspace ID is required...")` - No workspace ID provided
- `ForbiddenException("You do not have access to this workspace")` - User is not a workspace member

### PermissionGuard Errors

- `ForbiddenException("Authentication and workspace context required")` - Missing user or workspace context
- `ForbiddenException("You are not a member of this workspace")` - User not found in workspace
- `ForbiddenException("Insufficient permissions. Required: ...")` - User role doesn't meet requirements

## Migration Guide

### Before (Manual Checks):

```typescript
@Get()
async getTasks(@Request() req: any) {
  const workspaceId = req.user?.workspaceId;
  if (!workspaceId) {
    throw new UnauthorizedException("Authentication required");
  }
  return this.tasksService.findAll(workspaceId);
}
```

### After (Guard-Based):

```typescript
@Get()
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
@RequirePermission(Permission.WORKSPACE_ANY)
async getTasks(@Workspace() workspaceId: string) {
  return this.tasksService.findAll(workspaceId);
}
```

## Benefits

✅ **Declarative** - Permission requirements are clear from decorators
✅ **DRY** - No repetitive auth/workspace checks in every handler
✅ **Type-safe** - Workspace ID is guaranteed to exist when using `@Workspace()`
✅ **Secure** - RLS context automatically set, defense in depth
✅ **Testable** - Guards are independently testable
✅ **Maintainable** - Permission changes in one place

## Related Files

- `apps/api/src/lib/db-context.ts` - RLS utility functions
- `docs/design/multi-tenant-rls.md` - RLS architecture documentation
- `apps/api/prisma/schema.prisma` - Database schema with role definitions
