doce revapm phase 1

master-docs/00-system/05-PERMISSIONS-AND-ACCESS-CONTROL.md

@@ -0,0 +1,74 @@
+# Permissions and Access Control
+
+## Purpose
+Explain role-based permissions, account ownership rules, and how viewsets enforce access across the stack.
+
+## Code Locations (exact paths)
+- Role-based permissions: `backend/igny8_core/auth/permissions.py`
+- User roles and helpers: `backend/igny8_core/auth/models.py`
+- Account context middleware: `backend/igny8_core/auth/middleware.py`
+- Base viewsets with override/bypass logic: `backend/igny8_core/api/base.py`
+- DRF settings: `backend/igny8_core/settings.py`
+
+## High-Level Responsibilities
+- Enforce role-based access (developer, owner, admin, editor, viewer, system_bot).
+- Enforce tenant/site/sector scoping with selective overrides for privileged roles.
+- Block access when accounts lack active plans.
+
+## Detailed Behavior
+- Roles are stored on `User.role`; helper methods (`is_admin_or_developer`, `is_developer`, `is_system_account_user`, `has_role`) drive bypass logic.
+- Permission classes:
+  - `IsOwnerOrAdmin`: allows authenticated users with roles owner/admin/developer or superuser.
+  - `IsEditorOrAbove`: allows editor/admin/owner/developer or superuser.
+  - `IsViewerOrAbove`: allows any authenticated user.
+  - `AccountPermission`: ensures the user is authenticated, not a system bot unless intended, and matches object account when present; system bots bypass account checks.
+- Base viewsets:
+  - `AccountModelViewSet` filters by `account` unless `is_admin_or_developer` or `is_system_account_user` is true; create sets `account` automatically; delete protects system account slugs.
+  - `SiteSectorModelViewSet` extends filtering to `site`/`sector` when models have those fields.
+- Middleware:
+  - `AccountContextMiddleware` denies requests when user lacks an account or active plan (403/402), logging out session users and returning JSON errors.
+- System accounts (`aws-admin`, `default-account`, `default`) and system bots are privileged; system accounts are protected from deletion.
+
+## Data Structures / Models Involved (no code)
+- `User` with `role` and account FK.
+- `Account` with `status` and `plan` used for gating.
+- `SiteUserAccess` for per-site grants evaluated by `User.get_accessible_sites`.
+
+## Execution Flow
+- Middleware validates account/plan and sets `request.account`.
+- DRF authentication sets `request.user`; permission classes on views (and base viewsets) check role/account match.
+- Querysets are filtered by tenant/site/sector; privileged roles may bypass filtering.
+- Soft-delete or delete operations respect system account protection.
+
+## Cross-Module Interactions
+- All module viewsets inherit base classes, so account/site/sector scoping and role-based bypass apply uniformly.
+- Integration endpoints using API key auth rely on `request.site`/`request.account` set earlier.
+
+## State Transitions (if applicable)
+- Account status and plan activation affect access; changing these alters middleware decisions immediately due to per-request user refresh.
+
+## Error Handling
+- Middleware returns structured JSON errors for missing account or inactive plan.
+- Base viewsets wrap permission and validation failures into unified error responses.
+- Permission classes return standard DRF permission denials for unauthenticated/unauthorized users.
+
+## Tenancy Rules
+- Default: filter data to `request.account`; site/sector models further constrain by site/sector.
+- Overrides: developers/admins/system-account users can see across accounts; system bots can access any account/object; system accounts cannot be deleted.
+
+## Billing Rules (if applicable)
+- Active plan required; enforced in middleware before permission checks.
+
+## Background Tasks / Schedulers (if applicable)
+- Background tasks should be invoked with account/site identifiers to maintain the same isolation rules; role checks occur at request time, not within tasks.
+
+## Key Design Considerations
+- Centralize role checks to avoid per-view duplication.
+- Maintain middleware-first gating to prevent expensive processing before authorization.
+- Preserve protection of system accounts and allow ops-level overrides without compromising tenant isolation.
+
+## How Developers Should Work With This Module
+- Apply permission classes (`IsOwnerOrAdmin`, `IsEditorOrAbove`, etc.) on viewsets/endpoints as needed.
+- Always inherit from `AccountModelViewSet`/`SiteSectorModelViewSet` for scoped data access.
+- Avoid bypassing middleware plan checks; if admin-only, use explicit admin routes instead.
+- When adding new privileged behaviors, reuse `User` role helpers and system-account detection.