create-lego-one 2.0.10 → 2.0.13

package/template/docs/framework/plans/05-multitenancy-rbac.md

@@ -0,0 +1,1527 @@
+# Multitenancy and RBAC Implementation Plan
+
+> **For AI Implementing This Plan:** This is document 05 of 13. Complete documents 01-04 first.
+
+**Goal:** Implement complete multi-tenancy with organizations and full role-based access control (RBAC) system including roles, permissions, and user management.
+
+**Architecture:** Organization-based multi-tenancy with data isolation via PocketBase API rules. RBAC system with roles (Owner, Admin, Member, Guest) and granular permissions. Admin manages users and roles through settings UI.
+
+**Tech Stack:** PocketBase collections, React hooks, TanStack Query, Zustand, Zod validation
+
+---
+
+## Prerequisites
+
+- ✅ Completed `01-infrastructure-setup.md`
+- ✅ Completed `02-pocketbase-setup.md` (organizations, roles, permissions, user_roles collections)
+- ✅ Completed `03-host-kernel.md` (host app, shared state)
+- ✅ Completed `04-auth-system.md` (authentication, protected routes)
+
+---
+
+## Task 1: Create Multitenancy Types and Interfaces
+
+**Files:**
+- Create: `host/src/kernel/rbac/types.ts`
+
+### Step 1: Create RBAC types
+
+**File:** `host/src/kernel/rbac/types.ts`
+
+```typescript
+import type { Record } from 'pocketbase';
+
+// Organization types
+export interface Organization {
+  id: string;
+  name: string;
+  slug: string;
+  ownerId: string;
+  createdAt: string;
+  updated: string;
+}
+
+export interface CreateOrganizationData {
+  name: string;
+  slug: string;
+}
+
+export interface UpdateOrganizationData {
+  name?: string;
+  slug?: string;
+}
+
+// Role types
+export interface Role {
+  id: string;
+  name: string;
+  description?: string;
+  isSystem: boolean;
+  organizationId?: string;
+  createdAt: string;
+  updated: string;
+}
+
+export interface CreateRoleData {
+  name: string;
+  description?: string;
+  organizationId?: string;
+  permissions?: string[];
+}
+
+export interface UpdateRoleData {
+  name?: string;
+  description?: string;
+  permissions?: string[];
+}
+
+// Permission types
+export interface Permission {
+  id: string;
+  resource: string;
+  action: string;
+  description?: string;
+  createdAt: string;
+}
+
+// User role types
+export interface UserRole {
+  id: string;
+  userId: string;
+  roleId: string;
+  organizationId: string;
+  createdAt: string;
+}
+
+export interface AssignRoleData {
+  userId: string;
+  roleId: string;
+  organizationId: string;
+}
+
+// User management types
+export interface UserWithRoles {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+  roles: Array<{
+    id: string;
+    name: string;
+    organizationId: string;
+  }>;
+  organizations: string[];
+  createdAt: string;
+}
+
+export interface CreateUserRequest {
+  email: string;
+  name: string;
+  password: string;
+  organizationId: string;
+  roleIds?: string[];
+}
+
+export interface UpdateUserRequest {
+  name?: string;
+  email?: string;
+  avatar?: string;
+}
+
+// Permission check result
+export interface PermissionCheck {
+  allowed: boolean;
+  reason?: string;
+}
+
+// Resource types for permissions
+export type ResourceType =
+  | 'organizations'
+  | 'users'
+  | 'roles'
+  | 'permissions'
+  | 'todos'
+  | 'settings'
+  | 'audit_logs'
+  | 'all';
+
+// Action types for permissions
+export type ActionType =
+  | 'create'
+  | 'read'
+  | 'update'
+  | 'delete'
+  | 'manage'
+  | 'all';
+
+// System roles
+export const SYSTEM_ROLES = {
+  OWNER: 'Owner',
+  ADMIN: 'Admin',
+  MEMBER: 'Member',
+  GUEST: 'Guest',
+} as const;
+
+// Default permissions for system roles
+export const DEFAULT_ROLE_PERMISSIONS: Record<
+  string,
+  { resource: ResourceType; action: ActionType }[]
+> = {
+  [SYSTEM_ROLES.OWNER]: [
+    { resource: 'all', action: 'all' },
+  ],
+  [SYSTEM_ROLES.ADMIN]: [
+    { resource: 'organizations', action: 'read' },
+    { resource: 'organizations', action: 'update' },
+    { resource: 'users', action: 'create' },
+    { resource: 'users', action: 'read' },
+    { resource: 'users', action: 'update' },
+    { resource: 'users', action: 'delete' },
+    { resource: 'roles', action: 'read' },
+    { resource: 'permissions', action: 'read' },
+    { resource: 'todos', action: 'manage' },
+    { resource: 'settings', action: 'read' },
+    { resource: 'settings', action: 'update' },
+    { resource: 'audit_logs', action: 'read' },
+  ],
+  [SYSTEM_ROLES.MEMBER]: [
+    { resource: 'organizations', action: 'read' },
+    { resource: 'users', action: 'read' },
+    { resource: 'todos', action: 'manage' },
+    { resource: 'settings', action: 'read' },
+  ],
+  [SYSTEM_ROLES.GUEST]: [
+    { resource: 'organizations', action: 'read' },
+    { resource: 'todos', action: 'read' },
+  ],
+};
+```
+
+---
+
+## Task 2: Create RBAC Service
+
+**Files:**
+- Create: `host/src/kernel/rbac/service.ts`
+
+### Step 1: Create RBAC service
+
+**File:** `host/src/kernel/rbac/service.ts`
+
+```typescript
+import PocketBase from 'pocketbase';
+import type {
+  Organization,
+  CreateOrganizationData,
+  UpdateOrganizationData,
+  Role,
+  CreateRoleData,
+  UpdateRoleData,
+  Permission,
+  UserRole,
+  AssignRoleData,
+  UserWithRoles,
+  CreateUserRequest,
+  UpdateUserRequest,
+  PermissionCheck,
+  ResourceType,
+  ActionType,
+} from './types';
+import { SYSTEM_ROLES, DEFAULT_ROLE_PERMISSIONS } from './types';
+import type { ListResult } from 'pocketbase';
+
+export class RBACService {
+  constructor(private pb: PocketBase) {}
+
+  // ==================== Organization Management ====================
+
+  /**
+   * Get all organizations for current user
+   */
+  async getUserOrganizations(): Promise<Organization[]> {
+    try {
+      // The user's organizations are available via the relation
+      const userId = this.pb.authStore.record?.id;
+      if (!userId) return [];
+
+      // Get user record with expanded organizations
+      const userRecord = await this.pb.collection('users').getOne(userId, {
+        expand: 'organizations',
+      });
+
+      return (userRecord.expand?.organizations || []) as Organization[];
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get organization by ID
+   */
+  async getOrganization(id: string): Promise<Organization> {
+    try {
+      return await this.pb.collection('organizations').getOne(id);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get organization by slug
+   */
+  async getOrganizationBySlug(slug: string): Promise<Organization> {
+    try {
+      const result = await this.pb
+        .collection('organizations')
+        .getList(1, 1, { filter: `slug = "${slug}"` });
+      if (result.items.length === 0) {
+        throw new Error('Organization not found');
+      }
+      return result.items[0] as Organization;
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Create new organization
+   */
+  async createOrganization(data: CreateOrganizationData): Promise<Organization> {
+    try {
+      const userId = this.pb.authStore.record?.id;
+      if (!userId) throw new Error('Not authenticated');
+
+      const record = await this.pb.collection('organizations').create({
+        ...data,
+        ownerId: userId,
+      });
+
+      // Assign owner role to creator
+      const ownerRole = await this.getRoleByName(SYSTEM_ROLES.OWNER);
+      if (ownerRole) {
+        await this.assignRole({
+          userId,
+          roleId: ownerRole.id,
+          organizationId: record.id,
+        });
+      }
+
+      return record as Organization;
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Update organization
+   */
+  async updateOrganization(id: string, data: UpdateOrganizationData): Promise<Organization> {
+    try {
+      return await this.pb.collection('organizations').update(id, data);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Delete organization
+   */
+  async deleteOrganization(id: string): Promise<void> {
+    try {
+      await this.pb.collection('organizations').delete(id);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  // ==================== Role Management ====================
+
+  /**
+   * Get all roles for an organization
+   */
+  async getOrganizationRoles(organizationId: string): Promise<Role[]> {
+    try {
+      const result = await this.pb.collection('roles').getList(1, 100, {
+        filter: `organizationId = "${organizationId}" || organizationId = ""`,
+      });
+      return result.items as Role[];
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get role by ID
+   */
+  async getRole(id: string): Promise<Role> {
+    try {
+      return await this.pb.collection('roles').getOne(id);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get role by name
+   */
+  async getRoleByName(name: string): Promise<Role | null> {
+    try {
+      const result = await this.pb
+        .collection('roles')
+        .getList(1, 1, { filter: `name = "${name}" && organizationId = ""` });
+      if (result.items.length === 0) return null;
+      return result.items[0] as Role;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Create custom role
+   */
+  async createRole(data: CreateRoleData): Promise<Role> {
+    try {
+      return await this.pb.collection('roles').create({
+        name: data.name,
+        description: data.description,
+        organizationId: data.organizationId || '',
+        isSystem: false,
+      });
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Update role
+   */
+  async updateRole(id: string, data: UpdateRoleData): Promise<Role> {
+    try {
+      return await this.pb.collection('roles').update(id, data);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Delete role
+   */
+  async deleteRole(id: string): Promise<void> {
+    try {
+      await this.pb.collection('roles').delete(id);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  // ==================== Permission Management ====================
+
+  /**
+   * Get all permissions
+   */
+  async getAllPermissions(): Promise<Permission[]> {
+    try {
+      const result = await this.pb.collection('permissions').getList(1, 100, {
+        sort: 'resource,action',
+      });
+      return result.items as Permission[];
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Check if user has permission
+   */
+  async hasPermission(
+    userId: string,
+    organizationId: string,
+    resource: ResourceType,
+    action: ActionType
+  ): Promise<PermissionCheck> {
+    try {
+      // Get all user roles for this organization
+      const userRoles = await this.pb.collection('user_roles').getList(1, 50, {
+        filter: `userId = "${userId}" && organizationId = "${organizationId}"`,
+      });
+
+      if (userRoles.items.length === 0) {
+        return { allowed: false, reason: 'No roles assigned' };
+      }
+
+      const roleIds = userRoles.items.map((ur: any) => ur.roleId);
+
+      // Get all permissions for these roles
+      const permissions: Permission[] = [];
+
+      for (const roleId of roleIds) {
+        const role = await this.pb.collection('roles').getOne(roleId);
+
+        // If role has expand permissions
+        if (role.expand?.permissions) {
+          permissions.push(...role.expand.permissions);
+        }
+
+        // Check for system role defaults
+        if (role.isSystem) {
+          const defaults = DEFAULT_ROLE_PERMISSIONS[role.name];
+          if (defaults) {
+            // Convert defaults to Permission-like objects
+            for (const def of defaults) {
+              permissions.push({
+                id: `${def.resource}:${def.action}`,
+                resource: def.resource,
+                action: def.action,
+              } as Permission);
+            }
+          }
+        }
+      }
+
+      // Check for matching permission
+      const hasAll = permissions.some(p => p.resource === 'all' && p.action === 'all');
+      const hasResourceAll = permissions.some(p => p.resource === resource && p.action === 'all');
+      const hasActionAll = permissions.some(p => p.resource === 'all' && p.action === action);
+      const hasExact = permissions.some(p => p.resource === resource && p.action === action);
+
+      if (hasAll || hasResourceAll || hasActionAll || hasExact) {
+        return { allowed: true };
+      }
+
+      return { allowed: false, reason: 'Permission denied' };
+    } catch (error: any) {
+      return { allowed: false, reason: error.message };
+    }
+  }
+
+  /**
+   * Get user permissions for an organization
+   */
+  async getUserPermissions(
+    userId: string,
+    organizationId: string
+  ): Promise<{ resource: ResourceType; action: ActionType }[]> {
+    try {
+      const userRoles = await this.pb.collection('user_roles').getList(1, 50, {
+        filter: `userId = "${userId}" && organizationId = "${organizationId}"`,
+        expand: 'roleId',
+      });
+
+      const permissions: { resource: ResourceType; action: ActionType }[] = [];
+
+      for (const item of userRoles.items) {
+        const role = (item as any).expand?.roleId;
+        if (!role) continue;
+
+        if (role.isSystem) {
+          const defaults = DEFAULT_ROLE_PERMISSIONS[role.name];
+          if (defaults) {
+            permissions.push(...defaults);
+          }
+        }
+
+        if (role.expand?.permissions) {
+          for (const perm of role.expand.permissions) {
+            permissions.push({
+              resource: perm.resource as ResourceType,
+              action: perm.action as ActionType,
+            });
+          }
+        }
+      }
+
+      return permissions;
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  // ==================== User Management ====================
+
+  /**
+   * Get all users in an organization
+   */
+  async getOrganizationUsers(organizationId: string): Promise<UserWithRoles[]> {
+    try {
+      // Get users through the user_roles relation
+      const userRoles = await this.pb.collection('user_roles').getList(1, 100, {
+        filter: `organizationId = "${organizationId}"`,
+        expand: 'userId,roleId',
+      });
+
+      const usersMap = new Map<string, UserWithRoles>();
+
+      for (const item of userRoles.items) {
+        const ur = item as any;
+        const user = ur.expand?.userId;
+        const role = ur.expand?.roleId;
+
+        if (!user) continue;
+
+        if (!usersMap.has(user.id)) {
+          usersMap.set(user.id, {
+            id: user.id,
+            email: user.email,
+            name: user.name,
+            avatar: user.avatar,
+            roles: [],
+            organizations: [],
+            createdAt: user.created,
+          });
+        }
+
+        if (role) {
+          usersMap.get(user.id)!.roles.push({
+            id: role.id,
+            name: role.name,
+            organizationId: role.organizationId || organizationId,
+          });
+        }
+      }
+
+      return Array.from(usersMap.values());
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Assign role to user
+   */
+  async assignRole(data: AssignRoleData): Promise<UserRole> {
+    try {
+      return await this.pb.collection('user_roles').create(data);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Remove role from user
+   */
+  async removeRole(userRoleId: string): Promise<void> {
+    try {
+      await this.pb.collection('user_roles').delete(userRoleId);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Invite/create user in organization
+   */
+  async createUser(data: CreateUserRequest): Promise<void> {
+    try {
+      // Create user
+      const record = await this.pb.collection('users').create({
+        email: data.email,
+        password: data.password,
+        passwordConfirm: data.password,
+        name: data.name,
+        organizationId: data.organizationId,
+      });
+
+      // Assign roles if provided
+      if (data.roleIds && data.roleIds.length > 0) {
+        for (const roleId of data.roleIds) {
+          await this.assignRole({
+            userId: record.id,
+            roleId,
+            organizationId: data.organizationId,
+          });
+        }
+      }
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Update user
+   */
+  async updateUser(userId: string, data: UpdateUserRequest): Promise<void> {
+    try {
+      await this.pb.collection('users').update(userId, data);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Delete user
+   */
+  async deleteUser(userId: string): Promise<void> {
+    try {
+      await this.pb.collection('users').delete(userId);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  // ==================== Audit Logging ====================
+
+  /**
+   * Log an action
+   */
+  async logAction(data: {
+    userId: string;
+    organizationId: string;
+    action: string;
+    resource: string;
+    resourceId?: string;
+    details?: Record<string, any>;
+  }): Promise<void> {
+    try {
+      await this.pb.collection('audit_logs').create(data);
+    } catch (error) {
+      // Log errors should not fail the main operation
+      console.error('Failed to log action:', error);
+    }
+  }
+
+  /**
+   * Get audit logs for organization
+   */
+  async getAuditLogs(
+    organizationId: string,
+    page = 1,
+    perPage = 50
+  ): Promise<ListResult> {
+    try {
+      return await this.pb.collection('audit_logs').getList(page, perPage, {
+        filter: `organizationId = "${organizationId}"`,
+        sort: '-created',
+        expand: 'userId',
+      });
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Handle PocketBase errors
+   */
+  private handleError(error: any): Error {
+    if (error?.data?.message) {
+      return new Error(error.data.message);
+    }
+    if (error?.message) {
+      return new Error(error.message);
+    }
+    return new Error('An unexpected error occurred');
+  }
+}
+```
+
+---
+
+## Task 3: Create RBAC Hooks
+
+**Files:**
+- Create: `host/src/kernel/rbac/hooks.ts`
+
+### Step 1: Create RBAC hooks
+
+**File:** `host/src/kernel/rbac/hooks.ts`
+
+```typescript
+import { useCallback, useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { usePocketBase } from '../providers';
+import { RBACService } from './service';
+import type {
+  Organization,
+  CreateOrganizationData,
+  UpdateOrganizationData,
+  Role,
+  CreateRoleData,
+  UpdateRoleData,
+  Permission,
+  UserRole,
+  AssignRoleData,
+  UserWithRoles,
+  CreateUserRequest,
+  UpdateUserRequest,
+  ResourceType,
+  ActionType,
+} from './types';
+import { useGlobalKernelState } from '../shared-state';
+
+/**
+ * Get RBAC service instance
+ */
+function useRBACService(): RBACService | null {
+  const pb = usePocketBase();
+  if (!pb) return null;
+  return new RBACService(pb);
+}
+
+/**
+ * Manage current organization
+ */
+export function useCurrentOrganization() {
+  const { organization, setOrganization } = useGlobalKernelState();
+  const queryClient = useQueryClient();
+
+  const setCurrentOrganization = useCallback((org: Organization | null) => {
+    setOrganization(org);
+    // Clear related queries when switching organizations
+    queryClient.clear();
+  }, [setOrganization, queryClient]);
+
+  return {
+    organization,
+    setCurrentOrganization,
+  };
+}
+
+/**
+ * Get user's organizations
+ */
+export function useOrganizations() {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['organizations'],
+    queryFn: () => service?.getUserOrganizations() || [],
+    enabled: !!service,
+  });
+}
+
+/**
+ * Get single organization
+ */
+export function useOrganization(id: string) {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['organization', id],
+    queryFn: () => service?.getOrganization(id),
+    enabled: !!service && !!id,
+  });
+}
+
+/**
+ * Create organization
+ */
+export function useCreateOrganization() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+  const { setCurrentOrganization } = useCurrentOrganization();
+
+  return useMutation({
+    mutationFn: (data: CreateOrganizationData) => {
+      if (!service) throw new Error('Service not available');
+      return service.createOrganization(data);
+    },
+    onSuccess: (org) => {
+      queryClient.invalidateQueries({ queryKey: ['organizations'] });
+      setCurrentOrganization(org);
+    },
+  });
+}
+
+/**
+ * Update organization
+ */
+export function useUpdateOrganization() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateOrganizationData }) => {
+      if (!service) throw new Error('Service not available');
+      return service.updateOrganization(id, data);
+    },
+    onSuccess: (_, { id }) => {
+      queryClient.invalidateQueries({ queryKey: ['organization', id] });
+      queryClient.invalidateQueries({ queryKey: ['organizations'] });
+    },
+  });
+}
+
+/**
+ * Get organization roles
+ */
+export function useOrganizationRoles(organizationId: string | null) {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['roles', organizationId],
+    queryFn: () => {
+      if (!organizationId || !service) return [];
+      return service.getOrganizationRoles(organizationId);
+    },
+    enabled: !!service && !!organizationId,
+  });
+}
+
+/**
+ * Create custom role
+ */
+export function useCreateRole() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateRoleData) => {
+      if (!service) throw new Error('Service not available');
+      return service.createRole(data);
+    },
+    onSuccess: (_, { organizationId }) => {
+      queryClient.invalidateQueries({ queryKey: ['roles', organizationId] });
+    },
+  });
+}
+
+/**
+ * Update role
+ */
+export function useUpdateRole() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateRoleData }) => {
+      if (!service) throw new Error('Service not available');
+      return service.updateRole(id, data);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['roles'] });
+    },
+  });
+}
+
+/**
+ * Delete role
+ */
+export function useDeleteRole() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => {
+      if (!service) throw new Error('Service not available');
+      return service.deleteRole(id);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['roles'] });
+    },
+  });
+}
+
+/**
+ * Get all permissions
+ */
+export function usePermissions() {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['permissions'],
+    queryFn: () => service?.getAllPermissions() || [],
+    enabled: !!service,
+  });
+}
+
+/**
+ * Get organization users
+ */
+export function useOrganizationUsers(organizationId: string | null) {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['users', organizationId],
+    queryFn: () => {
+      if (!organizationId || !service) return [];
+      return service.getOrganizationUsers(organizationId);
+    },
+    enabled: !!service && !!organizationId,
+  });
+}
+
+/**
+ * Assign role to user
+ */
+export function useAssignRole() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: AssignRoleData) => {
+      if (!service) throw new Error('Service not available');
+      return service.assignRole(data);
+    },
+    onSuccess: (_, { organizationId }) => {
+      queryClient.invalidateQueries({ queryKey: ['users', organizationId] });
+    },
+  });
+}
+
+/**
+ * Remove role from user
+ */
+export function useRemoveRole() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ userRoleId, organizationId }: { userRoleId: string; organizationId: string }) => {
+      if (!service) throw new Error('Service not available');
+      return service.removeRole(userRoleId);
+    },
+    onSuccess: (_, { organizationId }) => {
+      queryClient.invalidateQueries({ queryKey: ['users', organizationId] });
+    },
+  });
+}
+
+/**
+ * Create user
+ */
+export function useCreateUser() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateUserRequest) => {
+      if (!service) throw new Error('Service not available');
+      return service.createUser(data);
+    },
+    onSuccess: (_, { organizationId }) => {
+      queryClient.invalidateQueries({ queryKey: ['users', organizationId] });
+    },
+  });
+}
+
+/**
+ * Update user
+ */
+export function useUpdateUser() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ userId, data }: { userId: string; data: UpdateUserRequest }) => {
+      if (!service) throw new Error('Service not available');
+      return service.updateUser(userId, data);
+    },
+    onSuccess: (_, { userId }) => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+      queryClient.invalidateQueries({ queryKey: ['auth', 'user'] });
+    },
+  });
+}
+
+/**
+ * Delete user
+ */
+export function useDeleteUser() {
+  const service = useRBACService();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ userId, organizationId }: { userId: string; organizationId: string }) => {
+      if (!service) throw new Error('Service not available');
+      return service.deleteUser(userId);
+    },
+    onSuccess: (_, { organizationId }) => {
+      queryClient.invalidateQueries({ queryKey: ['users', organizationId] });
+    },
+  });
+}
+
+/**
+ * Check permissions
+ */
+export function useHasPermission() {
+  const service = useRBACService();
+  const { user, organization } = useGlobalKernelState();
+
+  return useCallback(
+    async (resource: ResourceType, action: ActionType): Promise<boolean> => {
+      if (!service || !user?.id || !organization?.id) return false;
+      const result = await service.hasPermission(user.id, organization.id, resource, action);
+      return result.allowed;
+    },
+    [service, user, organization]
+  );
+}
+
+/**
+ * Get user permissions for current organization
+ */
+export function useUserPermissions() {
+  const service = useRBACService();
+  const { user, organization } = useGlobalKernelState();
+
+  return useQuery({
+    queryKey: ['permissions', 'user', user?.id, organization?.id],
+    queryFn: () => {
+      if (!service || !user?.id || !organization?.id) return [];
+      return service.getUserPermissions(user.id, organization.id);
+    },
+    enabled: !!service && !!user?.id && !!organization?.id,
+  });
+}
+
+/**
+ * Require permission - returns whether user has permission
+ */
+export function useRequirePermission(resource: ResourceType, action: ActionType) {
+  const permissions = useUserPermissions();
+  const [hasPermission, setHasPermission] = useState(false);
+
+  useEffect(() => {
+    const perms = permissions.data || [];
+
+    const allowed =
+      perms.some(p => p.resource === 'all' && p.action === 'all') ||
+      perms.some(p => p.resource === resource && p.action === 'all') ||
+      perms.some(p => p.resource === 'all' && p.action === action) ||
+      perms.some(p => p.resource === resource && p.action === action);
+
+    setHasPermission(allowed);
+  }, [permissions.data, resource, action]);
+
+  return {
+    hasPermission,
+    isLoading: permissions.isLoading,
+  };
+}
+
+/**
+ * Get audit logs
+ */
+export function useAuditLogs(organizationId: string | null, page = 1) {
+  const service = useRBACService();
+
+  return useQuery({
+    queryKey: ['audit-logs', organizationId, page],
+    queryFn: () => {
+      if (!organizationId || !service) return null;
+      return service.getAuditLogs(organizationId, page);
+    },
+    enabled: !!service && !!organizationId,
+  });
+}
+```
+
+---
+
+## Task 4: Create Organization Selector Component
+
+**Files:**
+- Create: `host/src/kernel/rbac/components/OrganizationSelector.tsx`
+
+### Step 1: Create organization selector
+
+**File:** `host/src/kernel/rbac/components/OrganizationSelector.tsx`
+
+```typescript
+import { useCurrentOrganization, useOrganizations } from '../hooks';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../../components/ui/dropdown-menu';
+import { Button } from '../../components/ui/button';
+import { Building2, ChevronDown, Loader2, Plus } from 'lucide-react';
+import { useNavigate } from '@modern-js/runtime/router';
+
+export function OrganizationSelector() {
+  const { organization, setCurrentOrganization } = useCurrentOrganization();
+  const { data: organizations, isLoading } = useOrganizations();
+  const navigate = useNavigate();
+
+  const handleSwitch = (orgId: string) => {
+    const org = organizations?.find(o => o.id === orgId);
+    if (org) {
+      setCurrentOrganization(org);
+    }
+  };
+
+  const handleCreate = () => {
+    navigate('/settings/organizations/new');
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline" className="gap-2">
+          <Building2 className="h-4 w-4" />
+          {isLoading ? (
+            <Loader2 className="h-4 w-4 animate-spin" />
+          ) : organization ? (
+            <span className="max-w-[150px] truncate">{organization.name}</span>
+          ) : (
+            <span>Select Organization</span>
+          )}
+          <ChevronDown className="h-4 w-4" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56" align="start">
+        <DropdownMenuLabel>Organizations</DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        {organizations?.map((org) => (
+          <DropdownMenuItem
+            key={org.id}
+            onClick={() => handleSwitch(org.id)}
+            className={organization?.id === org.id ? 'bg-accent' : ''}
+          >
+            <Building2 className="mr-2 h-4 w-4" />
+            <span className="flex-1 truncate">{org.name}</span>
+            {organization?.id === org.id && (
+              <span className="text-xs text-muted-foreground">Current</span>
+            )}
+          </DropdownMenuItem>
+        ))}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={handleCreate}>
+          <Plus className="mr-2 h-4 w-4" />
+          Create Organization
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+```
+
+---
+
+## Task 5: Create Permission Gate Component
+
+**Files:**
+- Create: `host/src/kernel/rbac/components/PermissionGate.tsx`
+
+### Step 1: Create permission gate component
+
+**File:** `host/src/kernel/rbac/components/PermissionGate.tsx`
+
+```typescript
+import { useRequirePermission } from '../hooks';
+import type { ResourceType, ActionType } from '../types';
+import { Alert, AlertDescription } from '../../components/ui/alert';
+import { Lock } from 'lucide-react';
+
+interface PermissionGateProps {
+  resource: ResourceType;
+  action: ActionType;
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+
+export function PermissionGate({
+  resource,
+  action,
+  children,
+  fallback,
+}: PermissionGateProps) {
+  const { hasPermission, isLoading } = useRequirePermission(resource, action);
+
+  if (isLoading) {
+    return (
+      <div className="flex min-h-[200px] items-center justify-center">
+        <div className="text-sm text-muted-foreground">Checking permissions...</div>
+      </div>
+    );
+  }
+
+  if (!hasPermission) {
+    return (
+      fallback || (
+        <Alert variant="destructive">
+          <Lock className="h-4 w-4" />
+          <AlertDescription>
+            You don't have permission to {action} {resource}.
+          </AlertDescription>
+        </Alert>
+      )
+    );
+  }
+
+  return <>{children}</>;
+}
+```
+
+---
+
+## Task 6: Update Topbar with Organization Selector
+
+**Files:**
+- Modify: `host/src/layout/Topbar.tsx`
+
+### Step 1: Add organization selector to topbar
+
+**File:** `host/src/layout/Topbar.tsx`
+
+```typescript
+import { useGlobalKernelState } from '../kernel/shared-state';
+import { Menu, Bell } from 'lucide-react';
+import { LogoutButton } from '../kernel/auth/components/LogoutButton';
+import { useAuth } from '../kernel/auth/hooks';
+import { OrganizationSelector } from '../kernel/rbac/components/OrganizationSelector';
+
+export function Topbar() {
+  const { toggleMobileMenu } = useGlobalKernelState();
+  const { isAuthenticated } = useAuth();
+
+  return (
+    <header className="sticky top-0 z-20 flex h-16 items-center gap-4 border-b bg-background px-6">
+      {/* Mobile menu button */}
+      <button
+        onClick={toggleMobileMenu}
+        className="lg:hidden rounded-lg p-2 text-muted-foreground hover:bg-muted"
+      >
+        <Menu className="h-5 w-5" />
+      </button>
+
+      {/* Organization selector */}
+      {isAuthenticated && <OrganizationSelector />}
+
+      {/* Breadcrumb/spacer */}
+      <div className="flex-1" />
+
+      {/* Actions */}
+      <div className="flex items-center gap-2">
+        {isAuthenticated && (
+          <button className="rounded-lg p-2 text-muted-foreground hover:bg-muted">
+            <Bell className="h-5 w-5" />
+          </button>
+        )}
+
+        {isAuthenticated && <LogoutButton />}
+      </div>
+    </header>
+  );
+}
+```
+
+---
+
+## Task 7: Create RBAC Context and Initial Organization Setup
+
+**Files:**
+- Create: `host/src/kernel/rbac/utils.ts`
+- Modify: `host/src/kernel/providers/PocketBaseProvider.tsx`
+
+### Step 1: Create RBAC utilities
+
+**File:** `host/src/kernel/rbac/utils.ts`
+
+```typescript
+import type { Organization } from './types';
+
+/**
+ * Initialize first organization for user if none exists
+ */
+export async function initializeFirstOrganization(
+  pb: any,
+  userId: string
+): Promise<Organization | null> {
+  try {
+    // Check if user has any organizations
+    const userRecord = await pb.collection('users').getOne(userId, {
+      expand: 'organizations',
+    });
+
+    const organizations = userRecord.expand?.organizations || [];
+
+    if (organizations.length > 0) {
+      return organizations[0] as Organization;
+    }
+
+    // Create default organization
+    const org = await pb.collection('organizations').create({
+      name: `${userRecord.name || 'User'}'s Organization`,
+      slug: `${userRecord.email?.split('@')[0] || 'user'}-${Date.now()}`,
+      ownerId: userId,
+    });
+
+    return org as Organization;
+  } catch (error) {
+    console.error('Failed to initialize organization:', error);
+    return null;
+  }
+}
+```
+
+### Step 2: Update PocketBaseProvider to initialize organization
+
+**File:** `host/src/kernel/providers/PocketBaseProvider.tsx`
+
+Add organization initialization after auth:
+
+```typescript
+import { createContext, useContext, useEffect, useState } from 'react';
+import PocketBase from 'pocketbase';
+import { useGlobalKernelState } from '../shared-state';
+import { initializeFirstOrganization } from '../rbac/utils';
+
+const PocketBaseContext = createContext<PocketBase | null>(null);
+
+export function PocketBaseProvider({ children }: { children: React.ReactNode }) {
+  const [pb, setPb] = useState<PocketBase | null>(null);
+  const { token, clearAuth, setOrganization } = useGlobalKernelState();
+
+  useEffect(() => {
+    // Initialize PocketBase client
+    const client = new PocketBase(import.meta.env.VITE_POCKETBASE_URL || 'http://127.0.0.1:8090');
+
+    // Load stored token
+    const storedToken = localStorage.getItem('pocketbase_auth');
+    if (storedToken) {
+      client.authStore.save(storedToken, null);
+    }
+
+    setPb(client);
+
+    // Set up auth cleanup on token invalidation
+    client.authStore.onChange(async (token, model) => {
+      if (!token) {
+        clearAuth();
+        localStorage.removeItem('pocketbase_auth');
+        setOrganization(null);
+      } else {
+        localStorage.setItem('pocketbase_auth', token);
+
+        // Initialize organization on login
+        if (model && !pb.authStore.record?.organizationId) {
+          const org = await initializeFirstOrganization(client, model.id);
+          if (org) {
+            setOrganization(org);
+          }
+        }
+      }
+    });
+
+    return () => {
+      // Cleanup on unmount
+    };
+  }, [clearAuth, setOrganization]);
+
+  // Update auth store when token changes in state
+  useEffect(() => {
+    if (pb && token && pb.authStore.token !== token) {
+      pb.authStore.save(token, null);
+    }
+  }, [pb, token]);
+
+  if (!pb) {
+    return null; // or a loading spinner
+  }
+
+  return (
+    <PocketBaseContext.Provider value={pb}>
+      {children}
+    </PocketBaseContext.Provider>
+  );
+}
+
+export function usePocketBase() {
+  const context = useContext(PocketBaseContext);
+  if (!context) {
+    throw new Error('usePocketBase must be used within PocketBaseProvider');
+  }
+  return context;
+}
+```
+
+---
+
+## Task 8: Create RBAC Module Barrel Export
+
+**Files:**
+- Create: `host/src/kernel/rbac/index.ts`
+
+### Step 1: Create barrel export
+
+**File:** `host/src/kernel/rbac/index.ts`
+
+```typescript
+export * from './types';
+export * from './service';
+export * from './hooks';
+export * from './components/PermissionGate';
+export * from './components/OrganizationSelector';
+export * from './utils';
+```
+
+---
+
+## Verification
+
+### Step 1: Build the host
+
+**Run:**
+
+```bash
+cd host
+pnpm run build
+```
+
+Expected: Build completes without errors.
+
+### Step 2: Start development server
+
+**Run:**
+
+```bash
+cd host
+pnpm run dev
+```
+
+Expected: Server starts on http://localhost:8080
+
+### Step 3: Test organization initialization
+
+1. Login with admin credentials
+2. After login, organization selector should appear in topbar
+3. First organization should be auto-created
+4. Should see organization name in dropdown
+
+### Step 4: Test organization switching (after implementing settings pages)
+
+1. Open organization selector dropdown
+2. Should list all user's organizations
+3. Switching should update current organization context
+
+---
+
+## Summary
+
+After completing this document, you will have:
+
+1. ✅ Complete RBAC service with organizations, roles, permissions, and users
+2. ✅ Organization selector component in topbar
+3. ✅ Permission gate component for protecting UI elements
+4. ✅ Hooks for managing organizations, roles, users, and permissions
+5. ✅ Auto-initialization of first organization for new users
+6. ✅ Organization context in global state
+7. ✅ System roles (Owner, Admin, Member, Guest) with default permissions
+8. ✅ Support for custom roles and permissions
+
+**Next:** `06-ui-components.md` - Complete Shadcn UI component library with all components.
+
+---
+
+## Files Created
+
+```
+host/
+└── src/
+    └── kernel/
+        ├── rbac/
+        │   ├── types.ts
+        │   ├── service.ts
+        │   ├── hooks.ts
+        │   ├── utils.ts
+        │   ├── components/
+        │   │   ├── OrganizationSelector.tsx
+        │   │   └── PermissionGate.tsx
+        │   └── index.ts
+        └── providers/
+            └── PocketBaseProvider.tsx (modified)
+```