Authorization, Ownership, RBAC & Permissions

# TaskFlow Phase 19 Authorization Matrix

| Operation | OWNER | ADMIN | MEMBER |
|---|---:|---:|---:|
| Read workspace/projects/tasks | yes | yes | yes |
| Create task | yes | yes | yes |
| Update any task | yes | yes | no |
| Update assigned task | yes | yes | yes |
| Delete task | yes | yes | no |
| Create/update project | yes | yes | no |
| Manage members | yes | yes | no |
| Manage workspace settings | yes | no | no |

Notes:
- This is the course policy, not a universal RBAC model.
- Object-level checks still apply after role-to-permission mapping.
- A MEMBER being able to update assigned tasks is relationship-based, not just role-based.
- The server rechecks authorization on every request.

# Linking Supabase Auth identity to TaskFlow User

Phase 18 gives NestJS a verified Supabase subject (`request.user.id`).
Phase 19 must map that external identity to the domain `User` row used by Membership and Task relations.

Recommended migration:
1. Add `authSubject String? @unique` to `User`.
2. Run a migration.
3. Sign in with the development Supabase account and inspect `/auth/me` to obtain the verified `sub`.
4. Link that `sub` to the intended TaskFlow User row using a trusted admin/dev path (Prisma Studio, SQL, or a one-time script).
5. Do not accept `authSubject` from an ordinary browser request body.
6. After all real users are linked, consider making the column required in a later migration.

Phase 19 source notes - verified September 18, 2026

NestJS Authorization
https://docs.nestjs.com/security/authorization

NestJS Execution Context / Reflector metadata
https://docs.nestjs.com/fundamentals/execution-context

OWASP Authorization Cheat Sheet
https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html

OWASP Business Logic Security Cheat Sheet
https://cheatsheetseries.owasp.org/cheatsheets/Business_Logic_Security_Cheat_Sheet.html

Core course locks remain unchanged:
- NestJS 12.0.3
- Prisma 7.9.1
- Supabase Auth stack from Phase 17

model User {
  id            String       @id @default(uuid())
  authSubject   String?      @unique
  email         String       @unique
  displayName   String?
  createdAt     DateTime     @default(now())
  updatedAt     DateTime     @updatedAt
  memberships   Membership[]
  assignedTasks Task[]       @relation("TaskAssignee")
}

// Phase 19 migration strategy:
// 1. Add authSubject as nullable + unique.
// 2. Link the development Supabase auth subject to the existing TaskFlow User.
// 3. Only make it required later if every application user is guaranteed to be linked.

import { Module } from '@nestjs/common'
import { PrismaModule } from '../prisma/prisma.module'
import { AuthorizationService } from './authorization.service'
import { WorkspacePermissionsGuard } from './workspace-permissions.guard'

@Module({
  imports: [PrismaModule],
  providers: [AuthorizationService, WorkspacePermissionsGuard],
  exports: [AuthorizationService, WorkspacePermissionsGuard],
})
export class AuthorizationModule {}

import { Injectable } from '@nestjs/common'
import type { MembershipRole } from '../generated/prisma/client'
import { PrismaService } from '../prisma/prisma.service'
import type { AuthenticatedUser } from '../auth/authenticated-user'
import { Permission } from './permissions'
import { ROLE_PERMISSIONS } from './role-permissions'
import {
  ApplicationUserNotLinkedException,
  PermissionDeniedException,
  WorkspaceAccessDeniedException,
  AuthorizedTaskNotFoundException,
} from '../common/errors/authorization.exceptions'

@Injectable()
export class AuthorizationService {
  constructor(private readonly prisma: PrismaService) {}

  async requireApplicationUser(auth: AuthenticatedUser) {
    const user = await this.prisma.user.findUnique({
      where: { authSubject: auth.id },

export enum Permission {
  WORKSPACE_READ = 'workspace.read',
  WORKSPACE_MANAGE = 'workspace.manage',
  MEMBER_MANAGE = 'member.manage',
  PROJECT_CREATE = 'project.create',
  PROJECT_UPDATE = 'project.update',
  TASK_READ = 'task.read',
  TASK_CREATE = 'task.create',
  TASK_UPDATE_ANY = 'task.update.any',
  TASK_UPDATE_ASSIGNED = 'task.update.assigned',
  TASK_DELETE = 'task.delete',
}

import { MembershipRole } from '../generated/prisma/client'
import { Permission } from './permissions'

export const ROLE_PERMISSIONS: Record<MembershipRole, ReadonlySet<Permission>> = {
  OWNER: new Set(Object.values(Permission)),
  ADMIN: new Set([
    Permission.WORKSPACE_READ,
    Permission.MEMBER_MANAGE,
    Permission.PROJECT_CREATE,
    Permission.PROJECT_UPDATE,
    Permission.TASK_READ,
    Permission.TASK_CREATE,
    Permission.TASK_UPDATE_ANY,
    Permission.TASK_DELETE,
  ]),
  MEMBER: new Set([
    Permission.WORKSPACE_READ,
    Permission.TASK_READ,
    Permission.TASK_CREATE,
    Permission.TASK_UPDATE_ASSIGNED,

import { Reflector } from '@nestjs/core'
import type { Permission } from './permissions'

export const RequireWorkspacePermissions = Reflector.createDecorator<Permission[]>()

import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common'
import { Reflector } from '@nestjs/core'
import type { FastifyRequest } from 'fastify'
import type { AuthenticatedUser } from '../auth/authenticated-user'
import { AuthorizationService } from './authorization.service'
import { RequireWorkspacePermissions } from './workspace-permissions.decorator'

@Injectable()
export class WorkspacePermissionsGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly authorization: AuthorizationService,
  ) {}

  async canActivate(context: ExecutionContext) {
    const required = this.reflector.getAllAndOverride(RequireWorkspacePermissions, [
      context.getHandler(),
      context.getClass(),
    ])
    if (!required?.length) {

import { ForbiddenException, NotFoundException } from '@nestjs/common'

export class ApplicationUserNotLinkedException extends ForbiddenException {
  constructor() {
    super({
      code: 'APPLICATION_USER_NOT_LINKED',
      message: 'The authenticated identity is not linked to a TaskFlow user.',
    })
  }
}

export class WorkspaceAccessDeniedException extends ForbiddenException {
  constructor() {
    super({ code: 'WORKSPACE_ACCESS_DENIED', message: 'You do not have access to this workspace.' })
  }
}

export class PermissionDeniedException extends ForbiddenException {
  constructor(permission: string) {
    super({ code: 'PERMISSION_DENIED', message: `Permission ${permission} is required.` })

import { ForbiddenException, Injectable } from '@nestjs/common'
import type { AuthenticatedUser } from '../auth/authenticated-user'
import { AuthorizationService } from '../authorization/authorization.service'
import { Permission } from '../authorization/permissions'
import { PrismaService } from '../prisma/prisma.service'

@Injectable()
export class TasksService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly authorization: AuthorizationService,
  ) {}

  async findOneForUser(auth: AuthenticatedUser, taskId: string) {
    const ctx = await this.authorization.requireTaskContext(auth, taskId)
    this.authorization.assertPermission(ctx.membership.role, Permission.TASK_READ)
    return this.prisma.task.findUniqueOrThrow({ where: { id: taskId } })
  }

  async updateForUser(auth: AuthenticatedUser, taskId: string, input: unknown) {

import { Controller, Param, Post, UseGuards } from '@nestjs/common'
import { SupabaseAuthGuard } from '../auth/supabase-auth.guard'
import { WorkspacePermissionsGuard } from '../authorization/workspace-permissions.guard'
import { RequireWorkspacePermissions } from '../authorization/workspace-permissions.decorator'
import { Permission } from '../authorization/permissions'

@Controller('workspaces/:workspaceId/projects')
@UseGuards(SupabaseAuthGuard, WorkspacePermissionsGuard)
export class WorkspaceProjectsController {
  @Post()
  @RequireWorkspacePermissions([Permission.PROJECT_CREATE])
  create(@Param('workspaceId') workspaceId: string) {
    // Delegate to a Project service. The guard has already verified
    // authenticated membership + coarse workspace permission.
    return { workspaceId }
  }
}

$api = 'http://127.0.0.1:4000'
$token = Read-Host 'Paste a current DEVELOPMENT access token'
$headers = @{ Authorization = "Bearer $token" }

Write-Host '1) No token -> 401'
try { Invoke-RestMethod "$api/tasks" } catch { $_.Exception.Response.StatusCode.value__ }

Write-Host '2) Authenticated but unrelated workspace -> 403 or scoped 404 depending endpoint policy'
# Replace with a workspace/task outside the authenticated user's membership.

Write-Host '3) Member can read workspace-scoped task -> 200'
# Invoke-RestMethod "$api/tasks/<member-visible-task-id>" -Headers $headers

Write-Host '4) Member updates assigned task -> success'
# Invoke-RestMethod ... -Method Patch -Headers $headers -ContentType 'application/json'

Write-Host '5) Member updates another member task -> 403'

Write-Host '6) Member deletes task -> 403'