create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/setup/10-auth-rbac.md

@@ -0,0 +1,497 @@
+# Authentication & RBAC
+
+**Authentication, Authorization, and Permission Management**
+
+---
+
+## Overview
+
+Lego-One provides complete authentication via PocketBase and Role-Based Access Control (RBAC) with organizations, roles, and permissions. All features are multi-tenant aware.
+
+---
+
+## Authentication System
+
+### PocketBase Auth
+
+**Collection:** `users`
+
+**Auth Methods:**
+- Email/password (via PocketBase)
+- Token persistence (localStorage)
+- Auto-refresh on app load
+
+### Auth Hooks
+
+#### useAuth()
+
+**Import:** `import { useAuth } from '@lego/kernel/auth'`
+
+**Returns:**
+```typescript
+{
+  user: User | null;           // Current user
+  token: string | null;        // Auth token
+  isAuthenticated: boolean;   // Auth status
+  isLoading: boolean;         // Loading state
+  login: (email, password) => Promise<void>;
+  register: (data) => Promise<void>;
+  logout: () => void;
+  updateProfile: (data) => Promise<void>;
+}
+```
+
+**Usage:**
+```typescript
+function MyComponent() {
+  const { user, isAuthenticated, logout } = useAuth();
+
+  if (!isAuthenticated) {
+    return <div>Please log in</div>;
+  }
+
+  return (
+    <div>
+      Welcome, {user?.name}
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+---
+
+#### useRequireAuth()
+
+**Purpose:** Automatically redirects to sign-in if not authenticated
+
+```typescript
+function ProtectedPage() {
+  useRequireAuth(); // Redirects to /sign-in if not authenticated
+
+  return <div>Protected content</div>;
+}
+```
+
+---
+
+### Protected Routes
+
+**In Host (modern.runtime.ts):**
+Routes with `protected: true` require authentication.
+
+```typescript
+routes: [
+  {
+    path: '/dashboard',
+    component: () => import('./pages/DashboardPage'),
+    protected: true, // Requires auth
+  },
+]
+```
+
+**In Plugins:**
+Plugins declare route protection in `plugin.config.ts`:
+
+```typescript
+routes: [
+  {
+    path: '/my-plugin',
+    component: () => import('./pages/MyPluginPage'),
+    protected: true, // Host will enforce this
+  },
+]
+```
+
+---
+
+## RBAC System
+
+### System Roles
+
+| Role | Description | Permissions |
+|------|-------------|-------------|
+| `Owner` | Organization owner | Full access (all:all) |
+| `Admin` | Organization admin | Users, roles, todos, settings |
+| `Member` | Regular member | Todos, read-only access |
+| `Guest` | Limited access | Read-only todos |
+
+### Permission Format
+
+**Resource:** What you're accessing (e.g., 'todos', 'users', 'settings')
+
+**Action:** What you're doing (e.g., 'read', 'write', 'delete', 'manage')
+
+**Examples:**
+- `todos.read` - Can view todos
+- `todos.write` - Can create/edit todos
+- `todos.delete` - Can delete todos
+- `users.manage` - Full user management
+- `settings.read` - Can view settings
+
+---
+
+### RBAC Hooks
+
+#### useCurrentOrganization()
+
+**Purpose:** Get/set current organization context
+
+```typescript
+import { useCurrentOrganization } from '@lego/kernel/rbac';
+
+function OrgSelector() {
+  const { organization, setCurrentOrganization } = useCurrentOrganization();
+
+  return (
+    <select value={organization?.id} onChange={(e) => {
+      const org = organizations.find(o => o.id === e.target.value);
+      setCurrentOrganization(org);
+    }}>
+      {organizations.map(org => (
+        <option key={org.id} value={org.id}>{org.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+#### useHasPermission()
+
+**Purpose:** Check if user has specific permission
+
+```typescript
+import { useHasPermission } from '@lego/kernel/rbac';
+
+function DeleteButton({ todoId }: { todoId: string }) {
+  const checkPermission = useHasPermission();
+  const [hasPermission, setHasPermission] = useState(false);
+
+  useEffect(() => {
+    checkPermission('todos', 'delete').then(setHasPermission);
+  }, [checkPermission]);
+
+  if (!hasPermission) return null;
+
+  return <button>Delete Todo</button>;
+}
+```
+
+---
+
+#### useRequirePermission()
+
+**Purpose:** Check permission and return loading state
+
+```typescript
+import { useRequirePermission } from '@lego/kernel/rbac';
+
+function AdminPanel() {
+  const { hasPermission, isLoading } = useRequirePermission('users', 'write');
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!hasPermission) return <div>Access denied</div>;
+
+  return <div>Admin content</div>;
+}
+```
+
+---
+
+#### useUserPermissions()
+
+**Purpose:** Get all user permissions for current organization
+
+```typescript
+import { useUserPermissions } from '@lego/kernel/rbac';
+
+function PermissionDebug() {
+  const { data: permissions } = useUserPermissions();
+
+  return (
+    <div>
+      <h4>Your Permissions:</h4>
+      <ul>
+        {permissions?.map(p => (
+          <li key={`${p.resource}:${p.action}`}>
+            {p.resource}:{p.action}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+#### useOrganizations()
+
+**Purpose:** Get all user's organizations
+
+```typescript
+import { useOrganizations } from '@lego/kernel/rbac';
+
+function OrganizationSwitcher() {
+  const { data: organizations } = useOrganizations();
+  const { setCurrentOrganization } = useCurrentOrganization();
+
+  return (
+    <select onChange={(e) => {
+      const org = organizations?.find(o => o.id === e.target.value);
+      setCurrentOrganization(org);
+    }}>
+      {organizations?.map(org => (
+        <option key={org.id} value={org.id}>{org.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+### Permission Gate Component
+
+**Purpose:** Conditionally render based on permission
+
+```typescript
+import { PermissionGate } from '@lego/kernel/rbac';
+
+function MyComponent() {
+  return (
+    <PermissionGate resource="todos" action="write">
+      <Button>Create Todo</Button>
+    </PermissionGate>
+  );
+}
+```
+
+**With Custom Fallback:**
+```typescript
+<PermissionGate
+  resource="todos"
+  action="delete"
+  fallback={<span className="text-muted-foreground">Insufficient permissions</span>}
+>
+  <Button>Delete Todo</Button>
+</PermissionGate>
+```
+
+---
+
+## Organization Management
+
+### Creating Organizations
+
+```typescript
+import { useCreateOrganization } from '@lego/kernel/rbac';
+
+function CreateOrganizationForm() {
+  const { mutate: createOrg, isPending } = useCreateOrganization();
+
+  const handleSubmit = (data: { name: string; slug: string }) => {
+    createOrg(data, {
+      onSuccess: (org) => {
+        console.log('Organization created:', org);
+        // Switch to new organization
+        setCurrentOrganization(org);
+      },
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="name" placeholder="Organization Name" />
+      <input name="slug" placeholder="Slug" />
+      <button disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Organization'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Organization Selector Component
+
+**Built-in component:** `OrganizationSelector`
+
+**Import:** `import { OrganizationSelector } from '@lego/kernel/rbac'`
+
+```typescript
+import { OrganizationSelector } from '@lego/kernel/rbac';
+
+function Topbar() {
+  return (
+    <header>
+      <OrganizationSelector />
+    </header>
+  );
+}
+```
+
+---
+
+## User Management
+
+### Getting Organization Users
+
+```typescript
+import { useOrganizationUsers } from '@lego/kernel/rbac';
+
+function UserList() {
+  const { data: users } = useOrganizationUsers(orgId);
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Email</th>
+          <th>Roles</th>
+        </tr>
+      </thead>
+      <tbody>
+        {users?.map(user => (
+          <tr key={user.id}>
+            <td>{user.name}</td>
+            <td>{user.email}</td>
+            <td>{user.roles.map(r => r.name).join(', ')}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+### Assigning Roles
+
+```typescript
+import { useAssignRole } from '@lego/kernel/rbac';
+
+function RoleSelector({ userId, organizationId }: Props) {
+  const { mutate: assignRole } = useAssignRole();
+  const { data: roles } = useOrganizationRoles(organizationId);
+
+  return (
+    <select onChange={(e) => {
+      assignRole({
+        userId,
+        roleId: e.target.value,
+        organizationId,
+      });
+    }}>
+      {roles?.map(role => (
+        <option key={role.id} value={role.id}>{role.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+## Plugin Permissions
+
+### Declaring Required Permissions
+
+In `plugin.config.ts`:
+
+```typescript
+export const pluginConfig: PluginConfig = {
+  manifest: {
+    name: '@lego/plugin-todo',
+    permissions: [
+      'todos.read',    // Required to view todos
+      'todos.write',   // Required to create/edit todos
+      'todos.delete',  // Required to delete todos
+    ],
+  },
+  // ...
+};
+```
+
+### Checking Permissions in Plugins
+
+```typescript
+import { useRequirePermission } from '@lego/kernel/rbac';
+
+function TodoPage() {
+  const { hasPermission: canRead } = useRequirePermission('todos', 'read');
+  const { hasPermission: canWrite } = useRequirePermission('todos', 'write');
+  const { hasPermission: canDelete } = useRequirePermission('todos', 'delete');
+
+  if (!canRead) {
+    return <div>You don't have permission to view todos</div>;
+  }
+
+  return (
+    <div>
+      {canWrite && <Button>Create Todo</Button>}
+      {/* Todo list */}
+      {canDelete && <Button>Delete Selected</Button>}
+    </div>
+  );
+}
+```
+
+---
+
+## PocketBase API Rules
+
+### Collection API Rules
+
+**These rules enforce data isolation and permissions at the database level:**
+
+```javascript
+{
+  name: 'todos',
+
+  // List: Users can view todos if they're in the org
+  listRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+
+  // View: Same as list
+  viewRule: '@request.auth.id != "" && organizationId = @request.auth.memberships.organizations',
+
+  // Create: Users can create todos in their orgs
+  createRule: '@request.auth.id != "" && organizationId = @request.auth.memberships.organizations',
+
+  // Update: Only todo owner can update
+  updateRule: '@request.auth.id != "" && organizationId = @request.auth.memberships.organizations && ownerId = @request.auth.id',
+
+  // Delete: Only todo owner can delete
+  deleteRule: '@request.auth.id != "" && organizationId = @request.auth.memberships.organizations && ownerId = @request.auth.id',
+}
+```
+
+---
+
+## Best Practices
+
+### Authentication
+
+1. **Always check `isAuthenticated`** before showing protected content
+2. **Use `useRequireAuth()`** for protected pages
+3. **Handle loading states** during auth checks
+4. **Clear sensitive data** on logout
+
+### Authorization
+
+1. **Scope all data to organization** - Always filter by `organizationId`
+2. **Check permissions before actions** - Use `useHasPermission()` or `PermissionGate`
+3. **Declare plugin permissions** - In `plugin.config.ts`
+4. **Use system roles** - Don't create roles unless needed
+
+### Multi-Tenancy
+
+1. **Always get org from kernel state** - Don't hardcode org IDs
+2. **Subscribe to org changes** - Refresh data when org changes
+3. **Include org in all queries** - Filter by `organizationId`
+4. **Set org on create** - Always set `organizationId` when creating records
+
+---
+
+**Next:** Read [`11-hooks-api.md`](./11-hooks-api.md) for complete hooks reference.