RBAC Permissions Architect

WORKSPACES (Containers)
    ↓
FEATURES (Modules)
    ↓
RBAC (Access Control)

• Workspaces: Organizations (root) and Projects (children)
• Features: Activatable modules with their own resources/permissions
• RBAC: Granular permissions grouped into roles

2. Critical Rules

• NO inheritance: Features and permissions DO NOT inherit between workspaces
• Contextual permissions: Permissions only apply in the workspace where assigned
• Special roles: Owner and Super Admin transcend normal permission rules
• Mandatory feature: permissions-management is always active
• Independence: Each workspace activates features explicitly

Architect Workflow for RBAC-Aware Features

Phase 1: Feature Scope Definition

Questions to answer:

1. Workspace scope: Does this feature apply to organizations, projects, or both?
2. Resource identification: What entities will users interact with?
3. Permission granularity: What actions can users perform on each resource?
4. Role requirements: Are there default roles needed for this feature?
5. Special role interaction: How do Owner/Super Admin interact with this feature?

Reference files to consult:

• Basic concepts: CONCEPTS.md - Workspace, Feature, Resource, Permission, Role definitions
• Workspace architecture: WORKSPACES.md - Organization vs Project behavior

Phase 2: Permission Matrix Design

Steps:

1. List all resources in your feature (e.g., boards, cards, comments)
2. Define CRUD+ actions for each resource (create, read, update, delete, custom actions)
3. Map to permission format: {resource}.{action} (e.g., boards.create, cards.move)
4. Consider visibility: Which permission grants UI visibility? (usually .read)
5. Document restrictions: What can Owner/Super Admin do that normal users cannot?

Example permission matrix:

Feature: kanban

Resources:
├─ boards
├─ cards
└─ card_comments

Permissions:
├─ boards.create
├─ boards.read      ← Grants visibility of Kanban in UI
├─ boards.update
├─ boards.delete
├─ cards.create
├─ cards.read
├─ cards.update
├─ cards.delete
├─ cards.move       ← Custom action
├─ card_comments.create
└─ card_comments.delete

Reference file to consult:

• Permission system: PERMISSIONS.md - Granular permissions, roles, verification flows

Phase 2.5: CASL Ability Definition

⚡ NEW: Authorization Layer Integration

After defining the permission matrix, specify how CASL (the project's authorization library) will implement these permissions.

Questions to answer:

1. Subject mapping: What are the CASL subjects for each resource?
2. Action alignment: Do CASL actions match permission actions perfectly?
3. Conditional rules: Are there context-dependent rules (e.g., "own resources only")?
4. Type safety: How do we enforce TypeScript types for subjects and actions?

CASL Subjects (PascalCase, Singular):

Map each database resource to a CASL subject:

// Database resources → CASL subjects
'boards'        → 'Board'
'cards'         → 'Card'
'card_comments' → 'Comment'

Rules:

• Use PascalCase for subjects (CASL convention)
• Use singular form (Board, not Boards)
• One resource = one subject (1:1 mapping)

CASL Actions:

Standard actions align with permissions:

'create' → boards.create
'read'   → boards.read
'update' → boards.update
'delete' → boards.delete

Custom actions:

'move'   → cards.move
'assign' → cards.assign

Ability Builder Template:

Include this in your PRD's entities.ts:

// ===== CASL Integration =====
import { AbilityBuilder, createMongoAbility, MongoAbility } from '@casl/ability';

// Define CASL types
type Subjects = 'Board' | 'Card' | 'Comment' | 'all';
type Actions = 'create' | 'read' | 'update' | 'delete' | 'move' | 'manage';
export type AppAbility = MongoAbility<[Actions, Subjects]>;

/**
 * Build CASL ability from user permissions
 *
 * @param user - Current user
 * @param workspace - Current workspace context
 * @param permissions - User's permissions in this workspace
 */
export function defineAbilitiesFor(
  user: User,
  workspace: Workspace,
  permissions: Permission[]
): AppAbility {
  const { can, cannot, build } = new AbilityBuilder<AppAbility>(createMongoAbility);

  // ===== Owner: Full access bypass =====
  if (user.id === workspace.owner_id) {
    can('manage', 'all');
    return build();
  }

  // ===== Super Admin: Full access with restrictions =====
  const orgId = workspace.parent_id || workspace.id;
  const isSuperAdmin = user.superAdminOrgs?.includes(orgId);

  if (isSuperAdmin) {
    can('manage', 'all');

    // Explicit restrictions (Super Admin CANNOT do these)
    cannot('delete', 'Organization');
    cannot('modify', 'User', { isOwner: true });
    cannot('assign', 'SuperAdminRole');

    return build();
  }

  // ===== Normal users: Map granular permissions =====
  permissions.forEach(perm => {
    const [resource, action] = perm.full_name.split('.');
    const subject = mapResourceToSubject(resource);
    can(action as Actions, subject);
  });

  return build();
}

/**
 * Map database resources to CASL subjects
 */
function mapResourceToSubject(resource: string): Subjects {
  const mapping: Record<string, Subjects> = {
    'boards': 'Board',
    'cards': 'Card',
    'card_comments': 'Comment',
  };
  return mapping[resource] || 'all';
}

React Integration Pattern:

Specify how UI components will use CASL:

// ===== React Context (features/rbac/context/AbilityContext.tsx) =====
import { createContext } from 'react';
import { AppAbility } from '../entities';

export const AbilityContext = createContext<AppAbility | null>(null);

// ===== Custom Hook (features/rbac/hooks/useAppAbility.ts) =====
import { useContext } from 'react';
import { AbilityContext } from '../context/AbilityContext';

export function useAppAbility() {
  const ability = useContext(AbilityContext);
  if (!ability) throw new Error('AbilityContext not provided');
  return ability;
}

// ===== Usage in Components =====
import { Can } from '@casl/react';
import { useAppAbility } from '@/features/rbac/hooks/useAppAbility';

function KanbanBoard() {
  const ability = useAppAbility();

  return (
    <div>
      {/* Declarative visibility with Can component */}
      <Can I="create" a="Board" ability={ability}>
        <CreateBoardButton />
      </Can>

      {/* Programmatic check */}
      {ability.can('delete', 'Board') && (
        <DeleteBoardButton />
      )}
    </div>
  );
}

⚠️ CRITICAL: CASL vs RLS

CASL and RLS serve different purposes:

┌─────────────────────────────────────────┐
│  CLIENT-SIDE (CASL)                     │
│  - UX authorization                      │
│  - Show/hide UI elements                │
│  - Enable/disable actions                │
│  - NOT security (can be bypassed)        │
└─────────────────────────────────────────┘
              ↓ HTTP Request
┌─────────────────────────────────────────┐
│  SERVER-SIDE (RLS)                      │
│  - REAL security                         │
│  - Database-level enforcement            │
│  - Cannot be bypassed                    │
│  - Final source of truth                 │
└─────────────────────────────────────────┘

Both are mandatory. CASL improves UX, RLS enforces security.

Deliverables for Phase 2.5:

In your PRD, include:

• CASL subject mapping table
• AppAbility type definition
• defineAbilitiesFor() function in entities.ts
• Owner bypass logic
• Super Admin bypass + restrictions
• Normal user permission mapping
• mapResourceToSubject() helper
• React integration examples (<Can>, hooks)
• Explanation of CASL vs RLS roles

Reference:

• CASL Official Docs: https://casl.js.org/v6/en/guide/intro
• CASL React Integration: https://casl.js.org/v6/en/package/casl-react

Phase 3: Special Roles Integration

Questions to answer:

1. Owner access: Does Owner have automatic full access? (Usually yes)
2. Super Admin access: Does Super Admin have full access? (Usually yes, with restrictions)
3. Protected actions: Are there actions only Owner can perform?
4. Project creation: If this is an org-level feature, can it create projects?

Critical rules:

• Owner and Super Admin bypass normal permission checks
• Owner can always manage Super Admins
• Super Admin cannot modify Owner or other Super Admins
• Super Admin cannot assign Super Admin role
• Only Owner can delete organizations

Reference file to consult:

• Special roles: SPECIAL_ROLES.md - Owner and Super Admin privileges, restrictions, hierarchy

Phase 4: Feature Activation Strategy

Questions to answer:

1. Default activation: Should this feature auto-activate in new workspaces?
2. Mandatory feature: Is this feature required system-wide? (Rare, only permissions-management)
3. Configuration options: Does the feature need workspace-specific config?
4. Dependencies: Does this feature require other features to be active?

Implementation in entities.ts:

// Feature definition (goes in global features catalog)
export const KanbanFeatureSchema = z.object({
  id: z.string().uuid(),
  slug: z.literal('kanban'),
  name: z.string(),
  description: z.string(),
  category: z.string(),
  is_mandatory: z.boolean().default(false),
});

// Workspace feature activation
export const WorkspaceFeatureSchema = z.object({
  workspace_id: z.string().uuid(),
  feature_id: z.string().uuid(),
  enabled: z.boolean().default(true),
  config: z.record(z.unknown()).optional(), // JSONB config
});

Reference file to consult:

• Feature system: FEATURES.md - Feature catalog, activation, independence

Phase 5: Visibility Rules with CASL

Design how users see this feature in the UI:

1. Minimum permission: What's the least permission needed to see the feature?
2. Owner/Super Admin: Always visible if feature is active
3. Normal users: Visible only if they have at least one permission
4. Component-level: Which UI elements require specific permissions?

CASL Integration for Visibility:

Use CASL's <Can> component and ability.can() checks for UI visibility:

// ===== Feature-Level Visibility =====
import { useAppAbility } from '@/features/rbac/hooks/useAppAbility';

function useFeatureVisibility(featureSlug: string) {
  const { user, workspace } = useWorkspace();
  const ability = useAppAbility();

  // Owner/Super Admin bypass
  if (user.isOwner || user.isSuperAdmin) {
    return isFeatureActive(featureSlug, workspace);
  }

  // Check if user has ANY permission from feature
  const feature = getFeature(featureSlug);
  const hasPermission = feature.resources.some(resource => {
    const subject = mapResourceToSubject(resource);
    return ability.can('read', subject);
  });

  return hasPermission;
}

// ===== Usage in Navigation =====
function Navigation() {
  const showKanban = useFeatureVisibility('kanban');

  return (
    <nav>
      {showKanban && (
        <NavItem href="/kanban">Kanban</NavItem>
      )}
    </nav>
  );
}

Component-Level Visibility with <Can>:

import { Can } from '@casl/react';
import { useAppAbility } from '@/features/rbac/hooks/useAppAbility';

function KanbanBoard({ board }: { board: Board }) {
  const ability = useAppAbility();

  return (
    <div>
      <h1>{board.name}</h1>

      {/* Declarative: Create Button */}
      <Can I="create" a="Card" ability={ability}>
        <CreateCardButton boardId={board.id} />
      </Can>

      {/* Declarative: Delete Button */}
      <Can I="delete" a="Board" ability={ability}>
        <DeleteBoardButton boardId={board.id} />
      </Can>

      {/* Programmatic: Conditional UI */}
      <div className="actions">
        {ability.can('update', 'Board') && (
          <EditBoardButton board={board} />
        )}
        {ability.can('move', 'Card') && (
          <DragAndDropHandle />
        )}
      </div>

      {/* Inverted: Show message when user CANNOT do something */}
      <Can not I="create" a="Card" ability={ability}>
        <p className="text-muted">
          You don't have permission to create cards
        </p>
      </Can>
    </div>
  );
}

Field-Level Visibility (Advanced):

CASL supports field-level permissions for fine-grained visibility:

// Define field-level permissions in ability
can('read', 'Board', ['name', 'description']); // Can see name and description
can('read', 'Board', ['budget'], { isOwner: true }); // Only owners see budget

// Check field access
const canSeeBudget = ability.can('read', 'Board', 'budget');

// UI implementation
function BoardDetails({ board }: { board: Board }) {
  const ability = useAppAbility();

  return (
    <div>
      <h2>{board.name}</h2>
      <p>{board.description}</p>

      {/* Budget only visible to owners */}
      {ability.can('read', subject('Board', board), 'budget') && (
        <div>Budget: ${board.budget}</div>
      )}
    </div>
  );
}

Loading State Pattern:

While abilities are loading, show skeleton UI:

function ProtectedPage() {
  const { ability, isLoading } = useAbilityWithLoading();

  if (isLoading) {
    return <SkeletonLoader />;
  }

  return (
    <Can I="read" a="Board" ability={ability}>
      <BoardList />
    </Can>
  );
}

Example visibility logic (CASL version):

// User sees "Kanban" in menu if:
// - Owner/Super Admin (ability.can('manage', 'all') === true), OR
// - Has ANY permission: ability.can('read', 'Board') || ability.can('create', 'Board') || ...

// User sees "Create Board" button if:
// - ability.can('create', 'Board') === true

Deliverables for Phase 5:

In your PRD, include:

• Feature-level visibility hook using CASL
• <Can> component usage examples for all major actions
• Programmatic ability.can() checks for conditional UI
• Field-level visibility examples (if applicable)
• Loading states while abilities are fetched
• Inverted checks (<Can not>) for permission denial messages

Reference file to consult:

• Visibility system: VISIBILITY.md - UI visibility, feature gates, permission-based rendering
• CASL React Docs: https://casl.js.org/v6/en/package/casl-react

Phase 6: Database Schema and Security Layers

Design RLS-ready schema:

1. Workspace foreign key: All feature tables MUST reference workspaces.id
2. RLS policies: Plan policies for Owner, Super Admin, and normal users
3. Multi-tenancy: Ensure workspace_id filters prevent cross-workspace access
4. Cascading deletes: Plan what happens when workspace is deleted

Example schema pattern:

CREATE TABLE kanban_boards (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  created_by UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- RLS Policy
CREATE POLICY "Users can access boards in their workspaces"
ON kanban_boards FOR SELECT
TO authenticated
USING (
  -- Owner bypass
  workspace_id IN (
    SELECT id FROM workspaces
    WHERE owner_id = auth.uid()
  )
  OR
  -- Super Admin bypass
  workspace_id IN (
    SELECT organization_id FROM organization_super_admins
    WHERE user_id = auth.uid()
  )
  OR
  -- Normal user with permission
  user_can(auth.uid(), 'read', 'boards', workspace_id)
);

⚡ Security Layers: CASL + RLS Coordination

CASL and RLS work together as defense in depth:

┌──────────────────────────────────────────────────────────┐
│                    USER INTERACTION                       │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│  LAYER 1: CASL (Client-Side Authorization)               │
│  Purpose: UX optimization                                 │
│  - Shows/hides UI elements                                │
│  - Disables buttons for unauthorized actions              │
│  - Prevents unnecessary API calls                         │
│  - Improves user experience                               │
│                                                            │
│  Security: ❌ NOT REAL SECURITY (can be bypassed)         │
└──────────────────────────────────────────────────────────┘
                           ↓
                    HTTP Request Sent
                           ↓
┌──────────────────────────────────────────────────────────┐
│  LAYER 2: RLS (Server-Side Security)                     │
│  Purpose: REAL security enforcement                       │
│  - Database-level access control                          │
│  - Cannot be bypassed by client                           │
│  - Enforced even if CASL is disabled/hacked               │
│  - Multi-tenant data isolation                            │
│                                                            │
│  Security: ✅ FINAL SOURCE OF TRUTH                       │
└──────────────────────────────────────────────────────────┘

Example Flow:

// ===== CLIENT SIDE =====
// Step 1: User clicks "Delete Board"
function BoardActions({ board }) {
  const ability = useAppAbility();

  // CASL check: Should we even show the button?
  if (!ability.can('delete', 'Board')) {
    return null; // Button not rendered
  }

  async function handleDelete() {
    // CASL check passed, send request
    const response = await fetch(`/api/boards/${board.id}`, {
      method: 'DELETE',
    });

    // If RLS denies, we get 403 error here
    if (!response.ok) {
      alert('Permission denied');
    }
  }

  return <button onClick={handleDelete}>Delete</button>;
}

// ===== SERVER SIDE (RLS) =====
-- Step 2: Supabase receives DELETE query
DELETE FROM kanban_boards WHERE id = '...';

-- Step 3: RLS policy checks
-- Policy evaluates:
-- 1. Is user the owner? workspace_id IN (SELECT ...)
-- 2. Is user super admin? workspace_id IN (SELECT ...)
-- 3. Does user have permission? user_can(auth.uid(), 'delete', 'boards', ...)

-- If ANY condition is true → DELETE succeeds
-- If ALL conditions are false → ERROR: permission denied

Why Both Layers?

Architectural Rules:

1. CASL mirrors RLS: CASL permissions should match what RLS allows
2. RLS is source of truth: If there's a conflict, RLS wins
3. Both are mandatory: Never rely on CASL alone for security
4. Test RLS independently: Assume CASL can be bypassed
5. Keep them in sync: When RLS changes, update CASL definitions

In Your PRD:

Document both layers:

## Security Architecture

### Client-Side Authorization (CASL)
- Users with `boards.create` permission see "Create Board" button
- Implemented via `<Can I="create" a="Board">`

### Server-Side Security (RLS)
- PostgreSQL policy enforces permission check
- Queries auth.uid() from JWT
- Calls user_can() function for verification

### Sync Strategy
- CASL abilities loaded from same permissions table as RLS
- Permissions cached for 5 minutes in TanStack Query
- Realtime invalidation ensures <500ms sync

Reference file to consult:

• Data model: DATA_MODEL.md - Tables, RLS patterns, database functions

Phase 7: PRD Documentation

Include in your PRD (00-master-prd.md):

1. Feature Metadata

   • Feature slug (e.g., kanban)
   • Feature category (e.g., productivity)
   • Target workspaces (organization, project, or both)

2. Permission Matrix

   • Complete list of resources
   • All permissions with format resource.action
   • Visibility permission (usually {primary_resource}.read)

3. Role Definitions (if creating default roles)

   • Role name and scope (organization/project)
   • Permissions assigned to each role
   • Use cases for each role

4. Special Role Behavior

   • What Owner can do
   • What Super Admin can do
   • Any restrictions or protected actions

5. Workspace Integration

   • How feature activates
   • Configuration options
   • Dependencies on other features

6. Data Contracts (in entities.ts)

   • Zod schemas for all resources
   • Feature definition schema
   • Permission schemas

Reference file to consult:

• Business rules: BUSINESS_RULES.md - Complete ruleset for workspaces, features, permissions, roles

Common Architect Mistakes to Avoid

General RBAC Mistakes

❌ Assuming feature inheritance between org and projects ✅ Each workspace activates features independently

❌ Creating "Owner of project" role ✅ Owner only exists at organization level

❌ Hardcoding Owner/Super Admin permissions in permission tables ✅ Owner/Super Admin use bypass logic, not permission tables

❌ Mixing business logic with permissions ✅ Permissions are pure access control; business rules go in use cases

❌ Forgetting workspace_id in entities ✅ All feature entities must reference workspace

❌ Creating permissions without resources ✅ Always define resources first, then permissions on those resources

❌ Ignoring RLS in schema design ✅ Plan RLS policies during entity design

CASL-Specific Mistakes

❌ Treating CASL as security ✅ CASL is UX authorization; RLS is real security

❌ Not defining CASL subjects in PRD ✅ Architect must specify subject mapping for each resource

❌ Using different permission formats in CASL vs database ✅ Maintain consistent resource.action format everywhere

❌ Forgetting cannot() rules for Super Admin restrictions ✅ Define explicit restrictions: cannot('delete', 'Organization')

❌ Not syncing CASL with RLS changes ✅ When RLS policies change, update defineAbilitiesFor() accordingly

❌ Hardcoding abilities instead of loading from database ✅ Load permissions from Supabase, then build CASL abilities dynamically

❌ Missing type safety for subjects and actions ✅ Define TypeScript types: type AppAbility = MongoAbility<[Actions, Subjects]>

❌ Not handling ability loading states ✅ Show skeleton UI while abilities are being fetched

Quick Reference Checklist

Before delivering PRD, verify:

Core RBAC

• Feature slug is unique and descriptive
• All resources identified and documented
• Permissions follow resource.action format
• Visibility permission clearly identified
• Owner behavior documented
• Super Admin restrictions documented
• Workspace scope defined (org/project/both)
• entities.ts includes all Zod schemas
• Schema includes workspace_id foreign keys
• RLS policies planned for all tables
• No assumptions about feature inheritance
• No "Owner of project" concepts

CASL Integration ⚡

• CASL subjects mapped (PascalCase, singular)
• AppAbility type defined with Actions and Subjects
• defineAbilitiesFor() function in entities.ts
• Owner bypass logic: can('manage', 'all')
• Super Admin restrictions: cannot() rules documented
• Normal user permission mapping implemented
• mapResourceToSubject() helper function included
• React integration examples (<Can>, useAppAbility)
• CASL vs RLS roles explained in PRD
• Loading states for abilities considered
• Type safety enforced for subjects and actions

Reference Files

Load these files as needed for detailed information:

• CONCEPTS.md: Core definitions (Workspace, Feature, Resource, Permission, Role)
• WORKSPACES.md: Organization vs Project architecture, independence rules
• FEATURES.md: Feature catalog, activation, configuration, independence
• PERMISSIONS.md: Granular permissions, roles, assignment, verification
• SPECIAL_ROLES.md: Owner and Super Admin privileges, restrictions, hierarchy
• VISIBILITY.md: UI visibility system, feature gates, permission-based rendering
• DATA_MODEL.md: Database schema patterns, RLS policies, functions
• BUSINESS_RULES.md: Complete ruleset (all RN-* rules from concepto-base.md)

Output Format

When using this skill, structure your PRD with these sections:

## Feature Metadata
- Slug: [feature-slug]
- Category: [category]
- Workspace Scope: [organization|project|both]
- Mandatory: [yes|no]

## Resources and Permissions

### Resources
- [resource-name]: [description]

### Permissions
- [resource].[action]: [description]

### Visibility Permission
- [resource].[action]: Grants UI visibility

## CASL Integration ⚡

### Subject Mapping
| Database Resource | CASL Subject |
|-------------------|--------------|
| boards            | Board        |
| cards             | Card         |
| card_comments     | Comment      |

### Actions
- Standard: `create`, `read`, `update`, `delete`
- Custom: `move`, `assign` (if applicable)

### Type Definition
```typescript
type Subjects = 'Board' | 'Card' | 'Comment' | 'all';
type Actions = 'create' | 'read' | 'update' | 'delete' | 'move' | 'manage';
export type AppAbility = MongoAbility<[Actions, Subjects]>;

Ability Builder

• Owner: can('manage', 'all')
• Super Admin: can('manage', 'all') + restrictions
• Normal users: Map from permissions table

React Integration

• Components use <Can I="action" a="Subject">
• Hooks use useAppAbility()

Role Definitions (if applicable)

[Role Name]

• Scope: [organization|project]
• Permissions: [list]
• Use Case: [description]

Special Role Behavior

Owner

• [specific behaviors]
• CASL: Full bypass via can('manage', 'all')

Super Admin

• [specific behaviors]
• Restrictions: [what they cannot do]
• CASL: cannot('delete', 'Organization'), etc.

Security Architecture

Client-Side Authorization (CASL)

• [How CASL controls UI visibility]
• Implemented via <Can> components and ability.can() checks

Server-Side Security (RLS)

• [How RLS enforces access control]
• PostgreSQL policies using user_can() function

Sync Strategy

• Permissions loaded from database
• CASL abilities built dynamically
• TanStack Query caching (5min stale time)
• Realtime invalidation (<500ms sync)

Workspace Integration

• Activation: [automatic|manual]
• Configuration: [config options]
• Dependencies: [required features]

Data Contracts (entities.ts)

[Zod schemas + CASL ability builder function]

## Final Note

This system is **highly modular and flexible**. The key is understanding that:

1. **Workspaces are independent** - No sharing, no inheritance
2. **Features are modular** - Can be activated anywhere
3. **Permissions are contextual** - Only apply in specific workspace
4. **Owner/Super Admin are special** - Bypass normal rules with specific restrictions

When in doubt, consult the reference files and remember: **explicit is better than implicit**.