init

docs/nav-rbac.md

@@ -0,0 +1,70 @@
+# Navigation RBAC
+
+## Overview
+
+Navigation visibility in this repo is driven by the Auth.js session and is treated as UX only. Real protection must still happen in route handlers and server-rendered pages.
+
+Current session fields used by navigation:
+
+- `systemRole`
+- `activeOrganizationId`
+- `activeMembershipRole`
+- `activeBusinessRole`
+- `activePermissions`
+
+## Access model
+
+### System role
+
+- `super_admin` is global and can see system-level areas such as `Workspaces`
+- `user` is the default system role
+
+### Workspace membership
+
+- `activeMembershipRole` represents the current workspace role, currently `admin | user`
+- `activeBusinessRole` represents the current IT Center profile in the selected workspace
+- `activePermissions` is the effective permission list for the selected workspace
+
+## Navigation config
+
+Navigation is configured in `src/config/nav-config.ts`.
+
+Supported access properties:
+
+- `systemRole`
+- `requireOrg`
+- `role`
+- `permission`
+- `plan`
+- `feature`
+
+Typical patterns:
+
+```ts
+access: { systemRole: 'super_admin' }
+access: { requireOrg: true, permission: 'asset:read' }
+access: { requireOrg: true, permission: 'master_data:manage' }
+```
+
+## Filtering behavior
+
+`src/hooks/use-nav.ts` reads the current Auth.js session and filters visible items client-side.
+
+Rules:
+
+- items with `systemRole` require a matching global role
+- items with `requireOrg` require an active workspace
+- items with `permission` require that permission in `activePermissions`
+- items with `role` require a matching `activeMembershipRole`
+
+`super_admin` can bypass workspace permission checks only after an active workspace is selected for workspace-scoped areas.
+
+## Server-side enforcement
+
+Use these helpers for real protection:
+
+- `requireSession()`
+- `requireSystemRole()`
+- `requireOrganizationAccess()`
+
+Do not rely on hidden sidebar items as security.